PtConnectionAddMsgHandlers()

Add a set of message handlers to a server connection object

Synopsis:

int PtConnectionAddMsgHandlers(
        PtConnectionServer_t *connection,
        PtConnectionMsgHandler_t const handlers[],
        unsigned nhandlers );

Library:

ph

Description:

This function adds a set of message handlers to a server connection object. The handlers[] argument points to an array of PtConnectionMsgHandler_t structures:

typedef void const *PtConnectionMsgFunc_t(
    PtConnectionServer_t *connection, void *user_data,
    unsigned long type, void const *msg, unsigned len,
    unsigned *reply_len );

typedef struct Pt_connection_msg_handler {
    unsigned long type;
    PtConnectionMsgFunc_t *fun;
} PtConnectionMsgHandler_t;

These structures describe your message handler functions. Your message handler should have these arguments:

connection
a pointer to the connection structure
user_data
a pointer to the connection object's user data. This data is set with PtConnectionServerSetUserData().
type
the type of the message
msg
a pointer to the message
len
the size of msg, in bytes
reply_len
a pointer to the size of the returned value, in bytes

The array must be sorted with respect to the type field; it also must not be destroyed or modified as long as the connection object using it exists.

If you add multiple tables to a connection object, they're searched in the reverse order: a call to PtConnectionAddMsgHandlers() can override handlers that were attached by a previous call.

A special value of zero in the type field means “any type.” When a message from a client arrives, all the tables are searched for an exact match on the type, and if this search fails, the tables is searched again for a handler with type 0.

A message handler can do one of three things:

A message handler shouldn't perform any blocking operations and isn't allowed to process Photon events (e.g. don't call PtBkgdHandlerProcess() from an event handler). There's no way to delay the reply to the client — if none of the handlers returns a non-NULL value, the library sends a zero-length reply.

Returns:

0
Success.
-1
An error occurred; errno is set.

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PtConnectionAddEventHandlers(), PtConnectionReply(), PtConnectionReplymx(), PtConnectionSend(), PtConnectionSendmx()

Connections in the Interprocess Communication chapter of the Photon Programmer's Guide