resmgr_context_t
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.