mb_receive
mb_receive
SYNOPSIS
int mb_receive( int socket, int *msg_id, int *msg_len, u_char **msg )
DESCRIPTION
mb_receive reads an incoming message.
socket is a connector returned by a previous call to mb_bind.
msg_id is a pointer to a request number which is used to uniquely identify the reply.
The message is read in *msg which points to a newly allocated area of memory. The length of the message is placed in *msg_len which must point to an integer.
mb_receive returns a message type which can be MB_ONEWAY, MB_TWOWAY or MB_MULTIWAY for a notification or a request message, MB_REPLY for a reply message, MB_NOBODY or MB_TIMEOUT for an error reply message, MB_REGISTER or MB_PROBE for an information message sent in response to a call to mb_register
or mb_probe.
| MB_ONEWAY | '1' | Message with no reply. |
| MB_TWOWAY | '2' | Message with a reply. |
| MB_MULTIWAY | 'M' | Broadcast message with no reply. |
| MB_REPLY | 'R' | Reply message to a previous MB_TWOWAY message. |
| MB_NOBODY | 'N' | Error message sent by the bus. |
| MB_TIMEOUT | 'T' | Error message sent by the bus. |
| MB_REGISTER | 'I' | Information message sent by the bus. |
| MB_PROBE | 'P' | Information message sent by the bus. |
When a MB_TWOWAY message is received, a call to mb_reply must be issued before the bus returns a
MB_TIMEOUT message to the calling process. The default time-out is 60 seconds. It can be changed by starting
the bus with a -t argument. The message identification placed in *msg_id must be saved and reused as an
argument to mb_reply.
A MB_REPLY message is received in response to a MB_TWOWAY message and a MB_ONEWAY or a MB_MULTIWAY message. In the first case, it contains whatever is returned by the peer process. In the other two cases, it contains an empty message returned by the bus to report a successful transmission.
MB_NOBODY and MB_TIMEOUT messages are empty. They signal an error. They are sent directly by the
bus when no process is registered under the name passed in argument to mb_send or if the called process
doesn’t reply in time to a MB_TWOWAY message.
MB_REGISTER and MB_PROBE messages are directly sent by the bus in response to a request message
of the same type. They contain a ‘\0’ terminated ASCII string representing the number of processes which are
registered under the name passed as a parameter to mb_register or mb_probe. This string can be converted to
an integer with atoi.
If nothing can be read from socket, mb_receive returns 0. If an error occurred, mb_receive returns -1 and the
global integer variable errno is set to indicate the error.
IMPORTANT: After processing a message, the memory allocated at the address *msg must be freed:
if ( *msg ) {
free( *msg );
}
Comments