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)