<HTML dir=ltr><HEAD>
<META http-equiv=Content-Type content="text/html; charset=unicode">
<META content="MSHTML 6.00.2900.3157" name=GENERATOR></HEAD>
<BODY>
<DIV><FONT face=Arial color=#000000 size=2>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?</FONT></DIV>
<DIV><FONT face=Arial size=2></FONT> </DIV>
<DIV>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT> </P>
<P class=MsoNormal><B><U><FONT face=Calibri size=4><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 14pt; FONT-FAMILY: Calibri">Startup and Shutdown:</SPAN></FONT></U></B></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">HANDLE rscmsg_Open(RSCMSG_LISTENERCALLBACK callback, void *cookie)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> – 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.</SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">void rscmsg_Close(HANDLE h)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> – Call this when its time to shutdown.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT> </P>
<P class=MsoNormal><B><U><FONT face=Calibri size=4><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 14pt; FONT-FAMILY: Calibri">Messaging:</SPAN></FONT></U></B></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">bool rscmsg_PostMessage(HANDLE h, string destination, RSCMSG_MESSAGE msg_data)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> - Send an asynchronous (non-blocking) message and don’t wait for a result. Returns true if message sent, false on error.</SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">bool SendMessage(HANDLE h, string destination, RSCMSG_MESSAGE msg_data, long *pResult)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> - 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. </SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">bool SendMessageTimeout(HANDLE h, string destination, RSCMSG_MESSAGE msg_data, long *pResult, unsigned long millisecond_timeout)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> - 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.</SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">bool SendMessageCallback(HANDLE h, string destination, RSCMSG_MESSAGE msg_data, RSCMSG_REPLYCALLBACK callback, void *cookie)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> - 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.</SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">bool rscmsg_BroadcastMessage(HANDLE h, RSCMSG_MESSAGE msg_data)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> - Broadcast an asynchronous (non-blocking) message and don’t wait for a result. Returns true if message sent, false on error. </SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">bool rscmsg_InitMessage(RSCMSG_MESSAGE *msg_data)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> – Initialize the message structure. The only this method does, aside from zeroing the memory, is to generate a new GUID for the id field.</SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">bool rscmsg_InitMessage(RSCMSG_MESSAGE *msg_data, long DataLength)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> – Initialize the message structure, generate a new GUID for the id field and finally, allocate a data buffer with the given number of bytes.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">Notes: </SPAN></FONT></P>
<UL style="MARGIN-TOP: 0in" type=disc>
<LI class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">The destination string has the format “ip-address:port”. i.e. “192.168.1.106:5534”</SPAN></FONT>
<LI class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">Use rscmsg_MemAlloc() to allocate the memory for your data in the <B><U><SPAN style="FONT-WEIGHT: bold">RSCMSG_MESSAGE</SPAN></U></B> struct. </SPAN></FONT></LI></UL>
<P class=MsoNormal><B><U><FONT face=Calibri size=4><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 14pt; FONT-FAMILY: Calibri">Support:</SPAN></FONT></U></B></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">void *rscmsg_MemAlloc (long size_in_bytes)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> – Allocate a block of memory.</SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">void rscmsg_MemFree (void *ptr)</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> – Free a block of memory allocated by rscmsg_MemAlloc().</SPAN></FONT></P>
<P class=MsoNormal><B><U><FONT face=Calibri size=3><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 12pt; FONT-FAMILY: Calibri">int rscmsg_GetLastError()</SPAN></FONT></U></B><FONT face=Calibri><SPAN style="FONT-FAMILY: Calibri"> – Return the error code for the last failed API call.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT> </P>
<P class=MsoNormal><B><U><FONT face=Calibri size=4><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 14pt; FONT-FAMILY: Calibri">Structures:</SPAN></FONT></U></B></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">typedef struct tagRSCMSG_MESSAGE</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">{</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"> GUID id; // internal use: unique message id number </SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"> uint32 flags; // internal use: various bitflags </SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"> byte priority; // Message priority. Default is 0. Range -128 to 127. Useful for sending out-of-band messages.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"> Int32 MessageCode; // Message code that you assign.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"> Int32 Param1; // application defined parameter of the message.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"> Int32 Param2; // application defined parameter of the message.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"> Int32 DataLength; // length of the binary data pointed to by ’Data’.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"> Void *Data; // Binary data. The length is specified by ‘DataLength’.</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT> </P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">} RSCMSG_MESSAGE;</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT> </P>
<P class=MsoNormal><B><U><FONT face=Calibri size=4><SPAN style="FONT-WEIGHT: bold; FONT-SIZE: 14pt; FONT-FAMILY: Calibri">Callbacks:</SPAN></FONT></U></B></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">typedef int (__stdcall *RSCMSG_LISTENERCALLBACK)(HANDLE h, RSCMSG_MESSAGE *msg, void *cookie);</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">typedef int (__stdcall *RSCMSG_REPLYCALLBACK)(HANDLE h, RSCMSG_MESSAGE *msg, void *cookie);</SPAN></FONT></P>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">Notes: </SPAN></FONT></P>
<UL style="MARGIN-TOP: 0in" type=disc>
<LI class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">Return RSCMSG_HANDLED when done processing a message. </SPAN></FONT>
<LI class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri">Don’t free the memory pointed to by msg->DataLength. </SPAN></FONT></LI></UL>
<P class=MsoNormal><FONT face=Calibri size=3><SPAN style="FONT-SIZE: 12pt; FONT-FAMILY: Calibri"></SPAN></FONT> </P></DIV></BODY></HTML>