baseinterface.h

Go to the documentation of this file.

/**********************************************************************
 *<
    FILE: baseInterface.h

    DESCRIPTION: Base classes for various interfaces in MAX

    CREATED BY: John Wainwright

    HISTORY: created 9/5/00

 *> Copyright (c) 2000 Autodesk, All Rights Reserved.
 **********************************************************************/

#pragma once

#include "maxheap.h"
#include "buildver.h"
#include "maxtypes.h"
#include "tab.h"

class InterfaceServer;
class BaseInterfaceServer;
class BaseInterface;
class InterfaceNotifyCallback;

// ID for BaseInterfaces
#define BASEINTERFACE_ID Interface_ID(0, 1)

// Base class for those classes and interfaces in MAX that can serve interfaces.  
class InterfaceServer: public MaxHeapOperators
{
public:
    // Note that this dtor should be pure virtual since this class is an interface 
    // and so it's meant to be instantiated directly.
    // Note that a virtual dtor requires an implementation.
    // For more info, see this MSDN article: ms-help://MS.MSDNQTR.v80.en/MS.MSDN.v80/MS.VisualStudio.v80.en/dv_vclang/html/8d7d1303-b9e9-47ca-96cc-67bf444a08a9.htm
    UtilExport virtual ~InterfaceServer();

    UtilExport virtual BaseInterface* GetInterface(Interface_ID id);
};

// The base class for interfaces in MAX R4.  
//   Provides basic identity, sub-interface access, lifetime management and 
//   cloning methods.   The base class for FPInterface in the FnPub system.
//  
class BaseInterface : public InterfaceServer
{
public:
    // Note that this dtor should be pure virtual since this class is an interface 
    // and so it's meant to be instantiated directly.
    UtilExport virtual ~BaseInterface();

    // from InterfaceServer
    UtilExport BaseInterface* GetInterface(Interface_ID id);

    // identification
    UtilExport virtual Interface_ID GetID();

    // interface lifetime management
    //   there is an implied Acquire() whenever an interface is served via a GetInterface()
    //   normally requiring a matching Release() from the client
    //   can optionally use LifetimeControl() method to inquire about actual
    //   lifetime policy of client and provide a server-controlled delete notify callback
    //      'noRelease' means don't need to call release, use interface as long as you like. 
    //      'immediateRelease' means the interface is good for only one call, but the release 
    //          is implied, you don't need to call release.
    //      'wantsRelease' means the clients are controlling lifetime so the interface needs 
    //          a Release() when the client has finished (default).
    //      'serverControlled' means the server controls lifetime and will use the InterfaceNotifyCallback 
    //          to tell you when it is gone.
    enum LifetimeType { noRelease, immediateRelease, wantsRelease, serverControlled }; 

    // LifetimeControl returns noRelease since 
    // AcquireInterface and ReleaseInterface do not perform 
    // any real acquiring and releasing (reference counting, etc.)
    // If the implementation of AcquireInterface and ReleaseInterface changes
    // in this class or derived classes, the return value of LifetimeControl 
    // needs to be updated accordingly.
    // RegisterNotifyCallback returns true if the callback will be called at or before deletion
    virtual LifetimeType    LifetimeControl() { return noRelease; }

    virtual bool            RegisterNotifyCallback(InterfaceNotifyCallback* incb) { UNUSED_PARAM(incb); return false; }
    virtual void            UnRegisterNotifyCallback(InterfaceNotifyCallback* incb) { UNUSED_PARAM(incb); }
    virtual BaseInterface*  AcquireInterface() { return (BaseInterface*)this; }; 
    virtual void            ReleaseInterface() { };

    // direct interface delete request
    virtual void            DeleteInterface() { };

    // interface cloning
    virtual BaseInterface*  CloneInterface(void* remapDir = NULL) { UNUSED_PARAM(remapDir); return NULL; }
};

// BaseInterface server specializes InterfaceServer with an implementation
//   based on a Tab<> of interface pointers for storing interfaces, 
//   typically extension interfaces, and providing an interface iteration
//   protocol.
//   class IObject in the FnPub system specializes BaseInterfaceServer 
class BaseInterfaceServer : public InterfaceServer
{
protected:
    Tab<BaseInterface*> interfaces;

public:
    // interface serving, default implementation looks in interfaces table
    UtilExport virtual BaseInterface* GetInterface(Interface_ID id);

    // interface enumeration...
    UtilExport virtual int NumInterfaces() const;

    UtilExport virtual BaseInterface* GetInterfaceAt(int i) const;

    // Note that this dtor should be pure virtual since this class is an interface 
    // and so it's meant to be instantiated directly.
    UtilExport virtual ~BaseInterfaceServer();
};

// InterfaceNotifyCallback base class,  //   can be specialized by clients of an interface that controls its own lifetime
//   so that they can be notified when the interface is deleted or other changes occur.
//   registered with the interface via the lifetime control protocol 
class InterfaceNotifyCallback: public MaxHeapOperators
{
public:
    // notify server is deleting  the interface
    virtual void InterfaceDeleted(BaseInterface* bi) { UNUSED_PARAM(bi); }

    // for future notification extensions
    virtual BaseInterface* GetInterface(Interface_ID id) { UNUSED_PARAM(id); return NULL; }
};