resmgr_context

Context information that's passed between resource-manager functions

Synopsis:

#include <sys/iofunc.h>
#include <sys/resmgr.h>

struct _extended_context {
        size_t                   length;
        struct _xendian_context  xendian;
        void                     *data; /* general purpose */
};

typedef struct _resmgr_context {
    int                         rcvid;
    struct _msg_info            info;
    resmgr_iomsgs_t             *msg;
    dispatch_t                  *dpp;
    int                         id;
    struct _extended_context    *extra;
    size_t                      msg_max_size;
    long                        status;
    size_t                      offset;
    size_t                      size;
    iov_t                       iov[1];
} resmgr_context_t;

Description:

The resmgr_context_t structure defines context information that's passed to resource-manager functions.

Note: The message_context_t structure is identical to resmgr_context_t.

The members (labelled to indicate whether they are input, output, both or others) include:

rcvid (input)

The receive ID for the client that sent the resource manager the message currently being processed, except when the I/O function should not deal with the client directly. This occurs when processing combine messages for any but the last message in the series, and within an iofuncs.close_ocb handler, in which cases it will be 0 (such a handler can not deal directly with the client).

info (input)

A _msg_info structure that contains information about the message received by the resource manager.

msg (input/output)

A pointer to the buffer used to receive the message from the client (except in the case of an iofuncs.close_ocb handler). This can be used as a scratch buffer to build a reply for the client, but care should be taken to extract all needed data before doing so, and to not exceed the available size. This field is declared as union of all the possible message types.

dpp (internal use)

The dispatch handle, created by a successful call to dispatch_create().

id (input)

The link ID, returned by resmgr_attach().

extra (input)

A pointer to an _extended_context structure that includes the following:

length — the size of the _extended_context structure, in bytes
xendian — an _xendian_context structure that the library uses when handling endian-swapping across Qnet.
data — (QNX Neutrino 7.0 or later) A pointer that a resource manager can use for arbitrary data that it needs. The resource-manager framework doesn't use this member.

msg_max_size (input)

The size of the buffer that msg points to. This is the size used for receiving messages from clients. This can be configured at initialization time using the attr.msg_max_size parameter to resmgr_attach() or message_attach().

status (output)

A place to store the status of the current operation. If the resmgr library is doing a reply for you (e.g. you called resmgr_msgreply() or returned _RESMGR_NPARTS(x) from your I/O function), this will be used as the status argument in the call to MsgReply() or MsgReplyv(). Often this is the result of a client operation, such as the number of bytes sucessfully read by a client read() call. This is usually set with _RESMGR_STATUS() or one of the _IO_SET_*() macros (e.g. _IO_SET_READ_NBYTES()). This field gets initialized to zero before any I/O handler is called.

offset (input)

When handling messages after the first in a combine message, this field stores how far into the receive buffer the current message is stored (i.e., its offset).

Note: This field should not be used. The message_type_t* msg parameter of the I/O function points to this offset within the ctp->msg buffer (i.e., the receive buffer). This other field should be used instead.

size (input)

The number of valid bytes of client data in the message area. (That is pointed to by the message_type_t *msg parameter of the I/O function.) This is guaranteed to include at least the full size of the message header. For example, in a read handler, you are guaranteed a complete struct _io_read.

iov (output)

An I/O vector where you can place the data that you're returning to the client. This defaults to one entry, but can be configured by the attr.nparts_max parameter given to a resmgr_attach() or message_attach() call. If the library replies on your behalf (for example, because you call resmgr_msgreply() or return _RESMGR_NPARTS(n) where n is greater than 0), the data pointed to by the iov field gets copied back to the client.

Classification:

QNX Neutrino