tt_message_callback_add(library call) tt_message_callback_add(library call)




 NAME    [Toc]    [Back]
      tt_message_callback_add - register a callback function

 SYNOPSIS    [Toc]    [Back]
      #include <Tt/tt_c.h>
      Tt_status tt_message_callback_add(
      Tt_message m,
      Tt_message_callback f);

 DESCRIPTION    [Toc]    [Back]
      The tt_message_callback_add function registers a callback function to
      be automatically invoked by tt_message_receive(3) whenever a reply or
      other state-change to this message is returned.

      The callback is defined in Tt/tt_c.h - Tttt_c(5). If the callback
      returns TT_CALLBACK_CONTINUE, other callbacks will be run; if no
      callback returns TT_CALLBACK_PROCESSED, tt_message_receive returns the
      message.  If the callback returns TT_CALLBACK_PROCESSED, no further
      callbacks are invoked for this event; tt_message_receive does not
      return the message.

      The m argument is the opaque handle for the message involved in this
      operation.  The f argument is the message callback to be run.

      The pattern handle will be NULL if the message did not match a dynamic
      pattern.  This is usually the case for message callbacks.

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, the tt_message_callback_add function
      returns the status of the operation as one of the following Tt_status
      values:

      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_POINTER
                The pointer passed does not point to an object of the
                correct type for this operation.

 APPLICATION USAGE    [Toc]    [Back]
      These callbacks are invoked from tt_message_receive; the program must,
      therefore, call tt_message_receive when the file descriptor returned
      by tt_fd becomes active.

      The application can use tt_message_callback_add to create wrappers for
      ToolTalk messages.  For example, a library routine can construct a
      request, attach a callback to the message, send the message, and
      process the reply in the callback.  When the callback returns



                                    - 1 -       Formatted:  January 24, 2005






 tt_message_callback_add(library call) tt_message_callback_add(library call)




      TT_CALLBACK_PROCESSED, the message reply is not returned to the main
      program; the message and reply are, therefore, completely hidden.

 SEE ALSO    [Toc]    [Back]
      Tt/tt_c.h - Tttt_c(5), tt_message_receive(3).


                                    - 2 -       Formatted:  January 24, 2005