Given a type defined in the C API, how do I associate it with a C ++ class in a namespace?

Inheritance can be used by inheriting from ::Message

to Bla::Message

.

However, this only works efficiently if the C API deals with ::Message*

pointers, not objects ::Message

. This is probably not a problem, as most C libraries handle opaque pointers.

First, display the public C structure to the library users (examples won't use namespaces for simplicity):

typedef struct CMessage
{
    // Public data fields for the C API users.
    // Having such is **not** recommended when using this inheritance approach,
    // a completly opaque structure is recommended instead.
} CMessage;

      

        
        
        
      

    

Then the inner functions must be implemented as methods of the class Message

that inherits from CMessage

:

struct Message : CMessage
{
    // Fields can be safely added here, assuming one do not ever remove fields off
    // CMessage causing the reduction of it size.
    // All the fields defined here should be private to the implementation.

    int stuff;

    // Construct the Message and perhaps initialize CMessage fields.
    Message(int param)
    {
        this->stuff = param;
    }

    void DoStuff(int i)
    {
        // Perform heavy work on i
        this->stuff = i * 10;
    }
};

      

        
        
        
      

    

The methods must then be exported to the outside world using simple C functions that deal with the base CMessage

, the object as a pointer.

CMessage* msg_new(int k)
{
    return new(std::nothrow) Message(k);
}

void msg_do_stuff(CMessage* message, int i)
{
    return (static_cast<Message*>(message))->DoStuff(i);
}

void msg_free(CMessage* message)
{
    delete  (static_cast<Message*>(message));
}

      

        
        
        
      

    

Note the use of the std :: nothrow overload <new>

. This is used so that failed allocations return null instead of throwing an exception. This is because C is unaware of exceptions and well, like C ++ characters, exceptions are not guaranteed by the standardized binary level, and hence it is not safe to propagate them to external code.

Another interesting approach, not exactly what the question is asking, but still interesting COM- like interfaces.

This is C ++ specific (since it uses classes), but unlike exporting C ++ classes in the usual way, breaking compatibility between different compiler vendors who may use different symbolic representations for method names, a virtual method table is exported which is possibly will have the same layout for all compilers on the platform in question. This is because vtables are very trivial, so the ABI framework can define how a virtual method table should be allocated in memory, or there is a consensus on how to do this.

The COM approach is very common in the Windows world, Direct3D, for example, uses something like this to communicate with the outside world.

First, the class / struct layout must be exposed to the API user using abstract methods:

struct IMessage
{
    virtual ~IMessage() {}
    virtual void Release() = 0;
    virtual void DoStuff(int i) = 0;
};

      

        
        
        
      

    

Do not reorder or delete any of the methods if binary compatibility is violated. Likewise, if new methods are added, they should be at the very end of the interface.

Then a derived object outside of the interface must be implemented IMessage

:

struct Message : IMessage
{
    int stuff;

    Message(int param)
    {
        this->stuff = param;
    }

    ~Message()
    {
        // Perform cleanup
    }

    void Release()
    {
        // Release this Message object
        delete this;
    }

    void DoStuff(int i)
    {
        // Perform heavy work on i
        this->stuff = i * 10;
    }
};

      

        
        
        
      

    

To enable the API user to create an object, you must export a C function that returns an interface pointer.

// The user is responsible for releasing the returned object pointer by calling obj->Release();
IMessage* MessageCreate(int param)
{
    return new(std::nothrow) Message(param);
}

      

        
        
        
      

    

Typically this approach forces interface ( IMessage

) to inherit from IUnknown

in order to follow COM , but this is optional if the intent is purely similar to COM interfaces.