Message Service Interface

Message service library provides a method to register services, and request services by name. Names are completely arbitrary, other than the fact that they are nul terminated strings.

Include

#include <msgclient.h>
related headers which maybe interesting to browse - msgprotocol.h

Project Location

src/msgsvr/clientThe service library
src/msgsvr/serverThe service manager project
src/msgsvr/client/client_serverSimple application using message library to register a server - requires msgsvr to be active
src/msgsvr/client/client_clientSimple application using message library to request a service - requires msgsvr to be active

Library

msgclient

Required Libraries

shmem
syslog
containers

Types

TYPEUsage
server_function_tableserver_function_table _your_table_name[] = { ServerFunctionEntry(function_name),.... }
server_message_handlerA user defined function of the type
int CPROC server_message_handler( uint32_t SourceRouteID, uint32_t MsgID , uint32_t *params, uint32_t param_length , uint32_t *result, uint32_t *result_length );

Routines


uint32_t RegisterServiceEx

( char *name

, server_function_table functions

, int entries

, server_message_handler event_handler )

also referenced by these macros

RegisterService(name,function_table, number of entries ) Registers a service, specifying a function table, and count of entries in that table. RegisterServiceHandler( name, handler ) Registers a service, specifying a messag handler function instead of a table of functions.

Registers a service, by name. Result is a unique base message ID which should be used to send messages later. An application may register both a message handler and a message table. The handler is first called with the method, if it results failure(0), then if there is a function in the table of functions to call, that is invoked.

nameName of the service to register.
functionsAn array of service_table_function structures. May be passed as NULL for no table.
entriesThe count of entries in the table. This is often expressable as ( sizeof(table)/sizeof( server_function_table ) )
handlerA function to handle the messages. May be NULL for no function.

void CloseMessageService

( void )

Close the message service, releasing all resources, and issuing disconnects to services that had been requested. This is also done if the process exit()'s... which means a clean, volentary exit... (either returning from main, or issuing an exit)




int ProcessClientMessages

( void )

If the application needs to wait a significant amount of time while processing a message from another process, this can be called to handle other messages which may be queued. This is also registered as an IdleProc, and will be invoked if Idle() is invoked. (this is the preferred method, cause then all threads which have idle procs get a chance to process: timers, network, msgserver, display...)




uint32_t LoadService

( char *name

, EventHandlerFunction func )

int CPROC EventHandlerFunction(uint32_t MsgID , uint32_t*params , uint32_t paramlen)
  • MsgID - the message that the server sent as an event(no response required).
  • params - the message content
  • paramlen - the size of the params region, in bytes.

  • Requests a service. Result is a base message ID... which should be added to all message IDs sent to this service. If the result is 0, the service was not available, or for some reason failed to be available.




    uint32_t LoadServiceEx

    ( char *name

    , EventHandlerFunctionEx func )

    int CPROC EventHandlerFunctionEx(uint32_t SourceID , uint32_t MsgID , uint32_t*params , uint32_t paramlen)
  • SourceID - the ID that the message came from... can be used somewhere
  • MsgID - the message that the server sent as an event(no response required).
  • params - the message content
  • paramlen - the size of the params region, in bytes.

  • Requests a service. Result is a base message ID... which should be added to all message IDs sent to this service. If the result is 0, the service was not available, or for some reason failed to be available. This takes a extended version of the event handler function that is passed the SourceID.




    void UnloadService

    ( uint32_t MsgBase )

    Disconnects from a service, identified by the base Message ID (the result from LoadService or LoadServiceEx). Sends a disconnect to the server.




    int TransactServerMultiMessage

    ( uint32_t MsgOut

    , uint32_t buffers

    , uint32_t MsgIn

    , uint32_t BufferIn

    , uint32_t *LengthIn

    , ... )

    Send a request to a service, and wait for the result. This is THE function, all other functions are wrappers for simpler cases of this. The result of this function is FALSE on failure, otherwise it's success... If MsgIn, BufferIn, and LengthIn are all NULL, this function does not wait for a result, and behaves as a SendServerMessage...

    MsgOutMessage/command ID. This is often a value enumerated from 0, which results in being the index of the function in the table of message handling functions registered by the service. This value then has the server's unique MsgBase added to it, so that the message is routed to the correct place...
    buffersCount of buffer pairs sent as variable arguments at the end of these arguments
    MsgIdThe address of a uint32_t type variable which receives the response message ID from the server (should be MsgOut or'd with SERVER_SUCCESS or SERVER_FAILURE). May be NULL.
    BufferInPointer to a buffer to accept responce data from the service. May be NULL if no data is expected from the result
    LengthInPointer to a uint32_t type variable which receives the size of the buffer returned. (also, this value is the maximum size of the buffer which allows the library to protect the application from data overrun.)
    ...Varaible arguments at the end are pairs of (POINTER data, uint32_t length).




    int SendMultiServiceEvent

    ( uint32_t client_pid

    , uint32_t event_id

    , uint32_t parts

    , ... )

    Send an event from a service to a client.

    client_pidThe server recieves a process identifier of clients when they connect, and while they send messages... this is the ID which the server should send to specify which client gets the event.
    event_idMessage ID to send to the client. This message needs to be biased with the value returned from RegisterService (the registered service base message ID).
    partscount of (POINTER,uint32_t length) parameters passed as variable parameters.
    ...Varaible arguments at the end are pairs of ( [POINTER data, uint32_t length], [], ... )




    SPECIAL USAGE FUNCTIONS

    These functions are meant for internal usage really, only, however, some creative application may be able to use these.


    int TransactRoutedServerMultiMessageEx

    ( uint32_t RouteID

    , uint32_t MsgOut

    , uint32_t buffers

    , uint32_t MsgIn

    , uint32_t BufferIn

    , uint32_t *LengthIn

    , uint32_t timeout

    , ... )

    Send a request to a service, and wait for the result. This is THE function, all other functions are wrappers for simpler cases of this. The result of this function is FALSE on failure, otherwise it's success... If MsgIn, BufferIn, and LengthIn are all NULL, this function does not wait for a result, and behaves as a SendServerMessage...

    RouteIDMagic number from event messages... this is NOT the value returned from LoadService.
    MsgOutMessage/command ID. This is often a value enumerated from 0, which results in being the index of the function in the table of message handling functions registered by the service. This value then has the server's unique MsgBase added to it, so that the message is routed to the correct place... (maybe this only applies for non-RouteID functions...
    buffersCount of buffer pairs sent as variable arguments at the end of these arguments
    MsgIdThe address of a uint32_t type variable which receives the response message ID from the server (should be MsgOut or'd with SERVER_SUCCESS or SERVER_FAILURE). May be NULL.
    BufferInPointer to a buffer to accept responce data from the service. May be NULL if no data is expected from the result
    LengthInPointer to a uint32_t type variable which receives the size of the buffer returned. (also, this value is the maximum size of the buffer which allows the library to protect the application from data overrun.)
    timeoutA different timeout from the default, specified in milliseconds. If 0, the default timeout is used (2 seconds for Debug mode, and 200ms for release mode)
    ...Varaible arguments at the end are pairs of (POINTER data, uint32_t length).




    int ProbeClientAlive

    ( uint32_t RouteID )

    Requests of a specific client it's alive status... This is also an extra-short transaction... the client has a short time to respond with it's health. FALSE indicates that the client is no longer alive, otherwise it is alive.