tt_message_receive - receive a message
#include <Tt/tt_c.h> Tt_message tt_message_receive(void);
tt_message_receive(3) ToolTalk Functions tt_message_receive(3)
NAME
tt_message_receive - receive a message
SYNOPSIS
#include <Tt/tt_c.h>
Tt_message tt_message_receive(void);
DESCRIPTION
The tt_message_receive() function returns a handle for the next message
queued to be delivered to the process and also runs any message or pat-
tern callbacks applicable to the queued message.
If the return value of tt_message_status(3) for this message is
TT_WRN_START_MESSAGE, the ToolTalk service started the process to
deliver the queued message; the process must reply to this message. If
the return value of tt_message_receive() is zero, no message is avail-
able.
RETURN VALUE
Upon successful completion, the tt_message_receive() function returns
the handle for the message object. The application can use
tt_ptr_error(3) to extract one of the following Tt_status values from
the returned handle:
TT_OK The operation completed successfully.
TT_ERR_NOMP
The ttsession(1) process is not running and the ToolTalk
service cannot restart it.
TT_ERR_STATE
The Tt_message is in a Tt_state that is invalid for the
attempted operation.
APPLICATION USAGE
A zero value can occur if a message or pattern callback processes the
message. It can also occur if the interval is too long between the
time the file descriptor became active and the tt_message_receive()
call was made. In the latter case, the ToolTalk service will time out
and offer the message to another process.
The application should check the tt_message_uid(3) and tt_mes-
sage_gid(3) against the User ID and Group ID of the application receiv-
ing the messsage. If the UID and/or GID of the application do not match
that of the message then the receiving application should consider
failing the message with TT_DESKTOP_EACCES.
The application should use tt_free(3) to free any data stored in the
address returned by the ToolTalk API.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | library/tooltalk |
+---------------+------------------+
|Stability | Committed |
+---------------+------------------+
SEE ALSO
tt_c(5), tt_ptr_error(3), tt_free(3).
ToolTalk 1.3 1 March 1996 tt_message_receive(3)