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:

• Just return NULL. This means that the handler hasn't handled the message and another handler should be looked for in the tables.
• Set up a reply message, set *reply_len to the length of it, and return the pointer to the reply.
• Reply to the client by calling PtConnectionReply(), and then return any non-NULL value.

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

See also:

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

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