ToolTalk Support
****************

XEmacs ToolTalk API Summary
===========================

The XEmacs Lisp interface to ToolTalk is similar, at least in spirit, to the standard C ToolTalk API.  Only the message and pattern parts of the API are supported at present; more of the API could be added if needed.  The Lisp interface departs from the C API in a few ways:

  * ToolTalk is initialized automatically at XEmacs startup-time.  Messages can only be sent other ToolTalk applications connected to the same X11 server that XEmacs is running on.

  * There are fewer entry points; polymorphic functions with keyword arguments are used instead.

  * The callback interface is simpler and marginally less functional. A single callback may be associated with a message or a pattern; the callback is specified with a Lisp symbol (the symbol should have a function binding).

  * The session attribute for messages and patterns is always initialized to the default session.

  * Anywhere a ToolTalk enum constant, e.g. TT_SESSION, is valid, one can substitute the corresponding symbol, e.g. 'TT_SESSION.  This simplifies building lists that represent messages and patterns.

Sending Messages
================

Example of Sending Messages
---------------------------

Here's a simple example that sends a query to another application and then displays its reply.  Both the query and the reply are stored in the first argument of the message.

     (defun tooltalk-random-query-handler (msg)
       (let ((state (get-tooltalk-message-attribute msg 'state)))
         (cond
           ((eq state 'TT_HANDLED)
            (message (get-tooltalk-message-attribute msg arg_val 0)))
           ((memq state '(TT_FAILED TT_REJECTED))
            (message "Random query turns up nothing")))))

     (defvar random-query-message
       '(   class TT_REQUEST
            scope TT_SESSION
          address TT_PROCEDURE
               op "random-query"
             args '((TT_INOUT "?" "string"))
         callback tooltalk-random-query-handler))

     (let ((m (make-tooltalk-message random-query-message)))
       (send-tooltalk-message m))

Elisp Interface for Sending Messages
------------------------------------

 -- Function: make-tooltalk-message attributes
     Create a ToolTalk message and initialize its attributes. The value of ATTRIBUTES must be a list of alternating keyword/values, where keywords are symbols that name valid message attributes. For example:

            (make-tooltalk-message
              '(class TT_NOTICE
                scope TT_SESSION
                address TT_PROCEDURE
                op "do-something"
                args ("arg1" 12345 (TT_INOUT "arg3" "string"))))

     Values must always be strings, integers, or symbols that represent ToolTalk constants.  Attribute names are the same as those supported by set-tooltalk-message-attribute, plus args.

     The value of args should be a list of message arguments where each message argument has the following form:

          (mode [value [type]]) or just value

     Where MODE is one of TT_IN, TT_OUT, or TT_INOUT and TYPE is a string.  If TYPE isn't specified then int is used if VALUE is a number; otherwise string is used.  If TYPE is string then VALUE is converted to a string (if it isn't a string already) with prin1-to-string.  If only a value is specified then MODE defaults to TT_IN.  If MODE is TT_OUT then VALUE and TYPE don't need to be specified.  You can find out more about the semantics and uses of ToolTalk message arguments in chapter 4 of the ToolTalk Programmer's Guide.

 -- Function: send-tooltalk-message msg
     Send the message on its way.  Once the message has been sent it's almost always a good idea to get rid of it with destroy-tooltalk-message.

 -- Function: return-tooltalk-message msg &optional mode
     Send a reply to this message.  The second argument can be reply, reject or fail; the default is reply.  Before sending a reply, all message arguments whose mode is TT_INOUT or TT_OUT should have been filled in---see set-tooltalk-message-attribute.

 -- Function: get-tooltalk-message-attribute msg attribute &optional argn
     Returns the indicated ToolTalk message attribute.  Attributes are identified by symbols with the same name (underscores and all) as the suffix of the ToolTalk tt_message_<attribute> function that extracts the value.  String attribute values are copied and enumerated type values (except disposition) are converted to symbols; e.g. TT_HANDLER is 'TT_HANDLER, uid and gid are represented by fixnums (small integers), opnum is converted to a string, and disposition is converted to a fixnum.  We convert opnum (a C int) to a string (e.g. 123 => "123") because there's no guarantee that opnums will fit within the range of XEmacs Lisp integers.

     [TBD] Use the plist attribute instead of C API user attribute for user-defined message data.  To retrieve the value of a message property, specify the indicator for ARGN.  For example, to get the value of a property called rflag, use

             (get-tooltalk-message-attribute msg 'plist 'rflag)

     To get the value of a message argument use one of the arg_val (strings), arg_ival (integers), or arg_bval (strings with embedded nulls), attributes.  For example, to get the integer value of the third argument:

             (get-tooltalk-message-attribute msg 'arg_ival 2)

     As you can see, argument numbers are zero-based.  The type of each arguments can be retrieved with the arg_type attribute; however ToolTalk doesn't define any semantics for the string value of arg_type.  Conventionally string is used for strings and int for 32 bit integers.  Note that XEmacs Lisp stores the lengths of strings explicitly (unlike C) so treating the value returned by arg_bval like a string is fine.

 -- Function: set-tooltalk-message-attribute value msg attribute &optional argn
     Initialize one ToolTalk message attribute.

     Attribute names and values are the same as for get-tooltalk-message-attribute.  A property list is provided for user data (instead of the user message attribute); see get-tooltalk-message-attribute.

     Callbacks are handled slightly differently than in the C ToolTalk API. The value of CALLBACK should be the name of a function of one argument.  It will be called each time the state of the message changes. This is usually used to notice when the message's state has changed to TT_HANDLED (or TT_FAILED), so that reply argument values can be used.

     If one of the argument attributes is specified as arg_val, arg_ival, or arg_bval, then ARGN must be the number of an already created argument.  Arguments can be added to a message with add-tooltalk-message-arg.

 -- Function: add-tooltalk-message-arg msg mode type &optional value
     Append one new argument to the message.  MODE must be one of TT_IN, TT_INOUT, or TT_OUT, TYPE must be a string, and VALUE can be a string or an integer.  ToolTalk doesn't define any semantics for TYPE, so only the participants in the protocol you're using need to agree what types mean (if anything). Conventionally string is used for strings and int for 32 bit integers.  Arguments can initialized by providing a value or with set-tooltalk-message-attribute; the latter is necessary if you want to initialize the argument with a string that can contain embedded nulls (use arg_bval).

 -- Function: create-tooltalk-message
     Create a new ToolTalk message.  The message's session attribute is initialized to the default session.  Other attributes can be initialized with set-tooltalk-message-attribute. make-tooltalk-message is the preferred way to create and initialize a message.

 -- Function: destroy-tooltalk-message msg
     Apply tt_message_destroy to the message.  It's not necessary to destroy messages after they've been processed by a message or pattern callback, the Lisp/ToolTalk callback machinery does this for you.

Receiving Messages
==================

Example of Receiving Messages
-----------------------------

Here's a simple example of a handler for a message that tells XEmacs to display a string in the mini-buffer area.  The message operation is called emacs-display-string.  Its first (0th) argument is the string to display.

     (defun tooltalk-display-string-handler (msg)
       (message (get-tooltalk-message-attribute msg 'arg_val 0)))

     (defvar display-string-pattern
       '(category TT_HANDLE
            scope TT_SESSION
               op "emacs-display-string"
         callback tooltalk-display-string-handler))

     (let ((p (make-tooltalk-pattern display-string-pattern)))
       (register-tooltalk-pattern p))

Elisp Interface for Receiving Messages
--------------------------------------

 -- Function: make-tooltalk-pattern attributes
     Create a ToolTalk pattern and initialize its attributes. The value of attributes must be a list of alternating keyword/values, where keywords are symbols that name valid pattern attributes or lists of valid attributes.  For example:

            (make-tooltalk-pattern
              '(category TT_OBSERVE
                   scope TT_SESSION
                      op ("operation1" "operation2")
                    args ("arg1" 12345 (TT_INOUT "arg3" "string"))))

     Attribute names are the same as those supported by add-tooltalk-pattern-attribute, plus 'args.

     Values must always be strings, integers, or symbols that represent ToolTalk constants or lists of same.  When a list of values is provided all of the list elements are added to the attribute.  In the example above, messages whose op attribute is "operation1" or "operation2" would match the pattern.

     The value of ARGS should be a list of pattern arguments where each pattern argument has the following form:

          (mode [value [type]]) or just value

     Where MODE is one of TT_IN, TT_OUT, or TT_INOUT and TYPE is a string.  If TYPE isn't specified then int is used if VALUE is a number; otherwise string is used.  If TYPE is string then VALUE is converted to a string (if it isn't a string already) with prin1-to-string.  If only a value is specified then MODE defaults to TT_IN.  If MODE is TT_OUT then VALUE and TYPE don't need to be specified.  You can find out more about the semantics and uses of ToolTalk pattern arguments in chapter 3 of the ToolTalk Programmer's Guide.

 -- Function: register-tooltalk-pattern pat
     XEmacs will begin receiving messages that match this pattern.

 -- Function: unregister-tooltalk-pattern pat
     XEmacs will stop receiving messages that match this pattern.

 -- Function: add-tooltalk-pattern-attribute value pat indicator
     Add one value to the indicated pattern attribute. The names of attributes are the same as the ToolTalk accessors used to set them less the tooltalk_pattern_ prefix and the _add suffix.  For example, the name of the attribute for the tt_pattern_disposition_add attribute is disposition.  The category attribute is handled specially, since a pattern can only be a member of one category (TT_OBSERVE or TT_HANDLE).

     Callbacks are handled slightly differently than in the C ToolTalk API. The value of CALLBACK should be the name of a function of one argument.  It will be called each time the pattern matches an incoming message.

 -- Function: add-tooltalk-pattern-arg pat mode type value
     Add one fully-specified argument to a ToolTalk pattern.  MODE must be one of TT_IN, TT_INOUT, or TT_OUT.  TYPE must be a string.  VALUE can be an integer, string or nil. If VALUE is an integer then an integer argument (tt_pattern_iarg_add) is added; otherwise a string argument is added.  At present there's no way to add a binary data argument.

 -- Function: create-tooltalk-pattern
     Create a new ToolTalk pattern and initialize its session attribute to be the default session.

 -- Function: destroy-tooltalk-pattern pat
     Apply tt_pattern_destroy to the pattern.  This effectively unregisters the pattern.

 -- Function: describe-tooltalk-message msg &optional stream
     Print the message's attributes and arguments to STREAM.  This is often useful for debugging.