3

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 );
}
When a message is empty, *msg_len is 0 and so is *msg.

SEE ALSO

mb_send, mb_reply, mb_register, mb_probe

Comments

Your comment:
[p] [b] [i] [u] [s] [quote] [pre] [br] [code] [url] [email] strip help 2000

Enter a maximum of 2000 characters.
Improve the presentation of your text with the following formatting tags:
[p]paragraph[/p], [b]bold[/b], [i]italics[/i], [u]underline[/u], [s]strike[/s], [quote]citation[/quote], [pre]as is[/pre], [br]line break,
[url]http://www.izend.org[/url], [url=http://www.izend.org]site[/url], [email]izend@izend.org[/email], [email=izend@izend.org]izend[/email],
[code]command[/code], [code=language]source code in c, java, php, html, javascript, xml, css, sql, bash, dos, make, etc.[/code].