[Vortex] New to BEEP - need to create messaging API

[Yourch, Chris]

Below is the high-level spec for a messaging API I need to create. Just before I was about to start opening up sockets and create the API a co-worker mentioned BEEP. I took one look and I think BEEP can implement my API pretty easily. Can a BEEP expert comment on my spec and provide some example code? Provide some tips on where to start?
 

 

Startup and Shutdown:

HANDLE  rscmsg_Open(RSCMSG_LISTENERCALLBACK callback, void *cookie) - Call this to get everything initialized and ready for sending/receiving messages. Pass the listener callback that receives all messages plus an optional cookie that will be passed to the callback function. Returns a handle for use with the rest of the API functions. Call rscmsg_Close(h) with the handle when done.

void rscmsg_Close(HANDLE h) - Call this when its time to shutdown.

 

Messaging:

bool rscmsg_PostMessage(HANDLE h, string destination, RSCMSG_MESSAGE msg_data) - Send an asynchronous (non-blocking) message and don't wait for a result. Returns true if message sent, false on error.

bool SendMessage(HANDLE h, string destination, RSCMSG_MESSAGE msg_data, long *pResult) - Send a synchronous (blocking) message and wait for a result. Returns true if message sent and *pResult will be set by the message receiver, false on error. 

bool SendMessageTimeout(HANDLE h, string destination, RSCMSG_MESSAGE msg_data, long *pResult, unsigned long millisecond_timeout) - Send a synchronous (blocking) message and wait for given amount of time for a result. Returns true if message sent and *pResult will be set by the message receiver, false on error.

bool SendMessageCallback(HANDLE h, string destination, RSCMSG_MESSAGE msg_data, RSCMSG_REPLYCALLBACK callback, void *cookie) - Send an asynchronous (non-blocking) message and request a reply and return immediately. Returns true if message sent, false on error. On success, the callback function is called when the reply is available.

bool rscmsg_BroadcastMessage(HANDLE h, RSCMSG_MESSAGE msg_data) - Broadcast an asynchronous (non-blocking) message and don't wait for a result. Returns true if message sent, false on error. 

bool rscmsg_InitMessage(RSCMSG_MESSAGE *msg_data) - Initialize the message structure. The only this method does, aside from zeroing the memory, is to generate a new GUID for the id field.

bool rscmsg_InitMessage(RSCMSG_MESSAGE *msg_data, long DataLength) - Initialize the message structure, generate a new GUID for the id field and finally, allocate a data buffer with the given number of bytes.

Notes: 

*	The destination string has the format "ip-address:port". i.e. "192.168.1.106:5534" 
*	Use rscmsg_MemAlloc() to allocate the memory for your data in the RSCMSG_MESSAGE struct. 

Support:

void *rscmsg_MemAlloc (long size_in_bytes) - Allocate a block of memory.

void rscmsg_MemFree (void *ptr) - Free a block of memory allocated by rscmsg_MemAlloc().

int rscmsg_GetLastError() - Return the error code for the last failed API call.

 

Structures:

typedef struct tagRSCMSG_MESSAGE

{

    GUID id;                               // internal use: unique message id number       

    uint32 flags;                        // internal use: various bitflags 

    byte priority;                        // Message priority. Default is 0. Range -128 to 127. Useful for sending out-of-band messages.

    Int32 MessageCode;           // Message code that you assign.

    Int32 Param1;                      // application defined parameter of the message.

    Int32 Param2;                      // application defined parameter of the message.

    Int32 DataLength;               // length of the binary data pointed to by 'Data'.

    Void *Data;                         // Binary data. The length is specified by 'DataLength'.

 

} RSCMSG_MESSAGE;

 

Callbacks:

typedef int (__stdcall *RSCMSG_LISTENERCALLBACK)(HANDLE h,  RSCMSG_MESSAGE *msg, void *cookie);

typedef int (__stdcall *RSCMSG_REPLYCALLBACK)(HANDLE h,  RSCMSG_MESSAGE *msg, void *cookie);

Notes: 

*	Return RSCMSG_HANDLED when done processing a message. 
*	Don't free the memory pointed to by msg->DataLength. 

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.aspl.es/pipermail/vortex/attachments/20070816/c0c1e2c5/attachment.htm