CDE/cde/doc/C/guides/ttGuide/ch02.sgm

<!-- $XConsortium: ch02.sgm /main/8 1996/08/31 15:12:59 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->

<Chapter Id="TTUG.HTU.div.1">
<Title Id="TTUG.HTU.mkr.1">Using ToolTalk Messaging</Title>
<indexterm><primary>messages</primary><secondary>general information</secondary></indexterm>
<note>
<para>Some code fragments shown in this chapter are taken from a
ToolTalk demo program called <literal>broadcast</literal>. See the directory
<filename>/usr/dt/examples/tt</filename> for the source code, <filename>Makefile</filename>
and <filename>README</filename> file.
</para>
</note>
<Sect1 Id="TTUG.HTU.div.2">
<title>Telling Your Application about ToolTalk Functionality</title>
<para>Before your application can use the inter-operability functionality
provided by the ToolTalk service and the Messaging Toolkit, it needs to
know where the ToolTalk libraries and toolkit reside.
</para>
<Sect2 Id="TTUG.HTU.div.3">
<title>Using the Messaging Toolkit and Including ToolTalk Commands</title>
<para>To use the ToolTalk service, an application calls ToolTalk functions
from the ToolTalk application programming interface (API). The Messaging
Toolkit provides higher-level functions than the ToolTalk API, such as
functions to register with the ToolTalk service, to create message
patterns, to send messages, to receive messages, and to examine message
information. To modify your application to use the ToolTalk service and
toolkit, you must include the following header files:
</para>
<indexterm><primary>header files</primary></indexterm>
<programlisting>#include &lt;Tt/tt_c.h&gt;    /* ToolTalk Header File */
#include &lt;Tt/tttk.h&gt;    /* Messaging Toolkit Header File */
</programlisting>
</sect2>
<Sect2 Id="TTUG.HTU.div.4">
<title>Using the ToolTalk Library</title>
<indexterm><primary>library, ToolTalk</primary></indexterm>
<para>The ToolTalk library is located in the directory:
</para>
<programlisting>/usr/dt/lib
</programlisting>
<para>The library name is platform-dependent (for example, on Solaris it is named
<filename>libtt.so</filename> and on HP-UX is its named
<filename>libtt.sl</filename>).
</para>
</sect2>
</sect1>
<Sect1 Id="TTUG.HTU.div.5">
<title>Before You Start Coding</title>
<para>Before you can incorporate the Messaging Toolkit functionality into your
application, you need to determine the way that your tool will work with
other tools. There are several basic questions you need to ask:
</para>
<itemizedlist>
<listitem>
<para>How will these tools work together?
</para>
</listitem>
<listitem>
<para>What kinds of operations can these tools perform?
</para>
</listitem>
<listitem>
<para>What kinds of operations can these tools ask other tools to perform?
</para>
</listitem>
<listitem>
<para>What events will these tools generate that may interest other tools?
(What types of messages will these tools want to send?)
</para>
</listitem>
<listitem>
<para>What events generated by other tools will be of interest to these
tools? (What types of messages will these tools want to receive?)
</para>
</listitem>
</itemizedlist>
<para>To best answer these questions, you need to understand the difference
between events and operations, and how the ToolTalk service handles
messages regarding each of these.
</para>
<Sect2 Id="TTUG.HTU.div.6">
<title>What Is the Difference Between an Event and an Operation?</title>
<indexterm><primary>event defined</primary></indexterm>
<indexterm><primary>operation defined</primary></indexterm>
<para>An <emphasis>event</emphasis> is an announcement that something has happened. An event is
simply a news bulletin. The sending process has no formal expectations
as to whether any other process will hear about the event, or whether an
action is taken as a consequence of the event. When a process uses the
ToolTalk service to inform interested processes that an event has
occurred, it sends a <emphasis>notice</emphasis>. Since the sending process does not expect a
reply, an event cannot fail.
</para>
<para>An <emphasis>operation</emphasis> is an inquiry or an action. The requesting process makes an
inquiry or requests that an operation be performed. The requesting
process expects a result to be returned and needs to be informed of the
status of the inquiry or action. When a process uses the ToolTalk
service to ask another tool to perform an operation, it sends a <emphasis>request</emphasis>.
The ToolTalk service delivers the request to interested processes and
informs the sending process of the status of the request.
</para>
<Sect3 Id="TTUG.HTU.div.7">
<title>Sending Notices</title>
<para>When your application sends a ToolTalk notice, it will not receive a
reply or be informed about whether or not any tool pays attention to the
notice. It is important to make the notice an impartial report of the
event as it happens. For example, if your tool sends the Desktop
Services message <literal>Modified</literal>, it may expect any listening tools to react in
a given way. Your tool, however, should not care, and does not need to
be informed about whether any or no other tool reacts to the message; it
only wants to report the event, <Symbol>THE_USER_HAS_MADE_CHANGES_TO_THIS</Symbol>.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.8">
<title>Sending Requests</title>
<para>When your application sends a ToolTalk request, it expects one tool to
perform the indicated operation, or to answer the inquiry, and return a
reply message. For example, if your tool sends the Desktop Services
message <literal>Get_Modified</literal>, it should expect notification that the message was
delivered and the action performed. The ToolTalk service guarantees that
either a reply will be returned by the receiving process or the sender
will be informed of the request's failure.
</para>
<para>You can identify requests in three ways:
</para>
<itemizedlist>
<listitem>
<para>By identifying the operations requested by your tool that can fail.
</para>
</listitem>
<listitem>
<para>By identifying the operations your tool can perform for other tools.
</para>
</listitem>
<listitem>
<para>By identifying the operations your tool will want other tools to perform.
</para>
</listitem>
</itemizedlist>
<para>A good method to use to identify these operations is to develop a
scenario that outlines the order of events and operations that you
expect your tool to perform and have performed.
</para>
</sect3>
</sect2>
<Sect2 Id="TTUG.HTU.div.9">
<title>Developing a Scenario</title>
<para>A scenario outlines the order of the events and operations that a tool
will expect to perform and to have performed. For example, the following
scenario outlines the events a generic editor could expect to perform
and to have performed:
</para>
<orderedlist>
<listitem>
<para>User double-clicks on a document icon in the File Manager.
The file opens in the editor, which is started by the system if one is
not already running. (If another tool has modifications to the text
pending for the document, the user is asked whether the other tool
should save the text changes or revert to the last saved version of the
document.)
</para>
</listitem>
<listitem>
<para>User inserts text.
</para>
</listitem>
<listitem>
<para>User saves the document. (If another tool has modifications pending
for the document, the user is asked whether to modify the document.)
</para>
</listitem>
<listitem>
<para>User exits the editor. (If text has unsaved changes, the user is
asked whether to save or discard the changes before quitting the file.)
</para>
</listitem>
</orderedlist>
<para>Once the scenario is done, you can answer your basic questions.
</para>
<Sect3 Id="TTUG.HTU.div.10">
<title>How Will the Tools Work Together?</title>
<itemizedlist>
<listitem>
<para>The File Manager requests that an editor open a document for
editing.
</para>
</listitem>
<listitem>
<para>Each instance of the editor notifies other interested instances of
changes it makes to the state of the document.
</para>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.11">
<title>What Kinds of Operations Do the Tools Perform?</title>
<itemizedlist>
<listitem>
<para>Each instance of the editor can answer questions about itself and
its state, such as &ldquo;What is your status?&rdquo;
</para>
</listitem>
<listitem>
<para>Each instance of the editor has the capability of performing
operations such as:
</para>
<itemizedlist>
<listitem>
<para>Iconifying and de-iconifying
</para>
</listitem>
<listitem>
<para>Raising to front and lowering to back
</para>
</listitem>
<listitem>
<para>Editing a document
</para>
</listitem>
<listitem>
<para>Displaying a document (read-only)
</para>
</listitem>
<listitem>
<para>Quitting
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.12">
<title>What Kinds of Operations Can the Tools Ask Other Tools to Perform?</title>
<itemizedlist>
<listitem>
<para>The File Manager must request that the editor open a document for editing.
</para>
</listitem>
<listitem>
<para>An instance of the editor can ask another instance of the editor to save changes to the open document.
</para>
</listitem>
<listitem>
<para>An instance of the editor can ask another instance of the editor to revert to the last saved version of the open document.
</para>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.13">
<title>What Events Will the Tools Generate that May Interest Other Tools?</title>
<itemizedlist>
<listitem>
<para>The document has been opened.
</para>
</listitem>
<listitem>
<para>The document has been modified.
</para>
</listitem>
<listitem>
<para>The document has been reverted to last saved version.
</para>
</listitem>
<listitem>
<para>The document has been saved.
</para>
</listitem>
<listitem>
<para>An instance of the editor has been exited.
</para>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.14">
<title>What Events Generated by Other Tools Will Be of Interest to This Tool?</title>
<itemizedlist>
<listitem>
<para>The document has been opened.
</para>
</listitem>
<listitem>
<para>The document has been modified.
</para>
</listitem>
<listitem>
<para>The document has been reverted to last saved version.
</para>
</listitem>
<listitem>
<para>The document has been saved.
</para>
</listitem>
<listitem>
<para>An instance of the editor has been exited.
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<Sect1 Id="TTUG.HTU.div.15">
<title>Preparing Your Application for Communication</title>
<para>The ToolTalk service provides you with a complete set of functions for
application integration. Using the functionality provided with the
ToolTalk Messaging Toolkit, your applications can be made to &ldquo;speak&rdquo; to
other applications that are ToolTalk-compliant. This section describes
how to add the kinds of ToolTalk functions you need to include in your
application so that it can communicate with other ToolTalk-aware
applications that follow the same protocols.
</para>
<Sect2 Id="TTUG.HTU.div.16">
<title>Creating a Ptype File</title>
<indexterm><primary>ptype file, creating</primary></indexterm>
<para>The ToolTalk types mechanism is designed to help the ToolTalk service
route messages. When your tool declares a ptype (process type), the message patterns
listed in it are automatically registered. The ToolTalk service then
matches messages it receives to these registered patterns. These static
message patterns remain in effect until the tool closes communication
with the ToolTalk service.
</para>
<para>The ToolTalk Types Database already has installed ptypes for tools
bundled with this release. You can extract a list of the installed
ptypes from the ToolTalk Types Database, as follows:
</para>
<screen>% tt_type_comp -d <symbol role="variable">user | system | network</symbol> -P
</screen>
<para>The names of the ptypes are printed out in source format.
</para>
<para>To generate a list of the installed ptypes including their signatures:
</para>
<screen>% tt_type_comp -d <symbol role="variable">user | system | network</symbol> -p
</screen>
<para>For all other tools (that is, tools that are not included in this
release), you need to first create a ptype file to define the ptype for
your application, and then compile the ptype with the ToolTalk type
compiler, <filename>tt_type_comp</filename>. To define a ptype, you need to include the
following information in a file:
</para>
<itemizedlist>
<listitem>
<para>A process-type identifier (<literal>ptid</literal>).
</para>
</listitem>
<listitem>
<para>An optional start string &mdash; The ToolTalk service executes this command, if necessary, to start a process running the program.
</para>
</listitem>
<listitem>
<para>Signatures &mdash; Describes the <Symbol>TT_PROCEDURE</Symbol>-addressed messages that the
program wants to receive. Messages to be observed are described
separately from messages to be handled.
</para>
</listitem>
</itemizedlist>
<para>To create a ptype file, you can use any text editor
(such as <command>vi</command>, <command>emacs</command>, or <command>dtpad</command>).
</para>
<para>After you have created a ptype file, you need to install the ptype by
running the ToolTalk type compiler. On the command line, type:
</para>
<screen>% tt_type_comp <symbol role="variable">file_name.ptype</symbol>
</screen>
<para>where <symbol role="variable">file_name.ptype</symbol>
is the name of the ptype file.
</para>
<Sect3 Id="TTUG.HTU.div.17">
<title>Testing for Existing Ptypes in Current Session</title>
<indexterm><primary>ptypes, testing for existence of</primary></indexterm>
<para>The ToolTalk service provides the following function to test if a given
ptype is already registered in the current session:
</para>
<programlisting>tt_ptype_exists(const char *ptype_id)
</programlisting>
<para>where <symbol role="variable">ptype_id</symbol> is the identifier of the session to test for registration.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.18">
<title>Merging a Compiled Ptype File into a Currently Running ttsession</title>
<para>The ToolTalk service provides the following function to merge a compiled
ToolTalk type file into the currently running <literal>ttsession</literal>:
</para>
<programlisting>tt_session_types_load (
            const char  *session,
            const char  *compile_types_file)
</programlisting>
<para>where <symbol role="variable">session</symbol> is the current default ToolTalk session and
<symbol role="variable">compiled_types_file</symbol> is the name of the compiled ToolTalk types file.
This function adds new types and replaces existing types of the same
name; other existing types remain unchanged.
</para>
</sect3>
</sect2>
<Sect2 Id="TTUG.HTU.div.19">
<title>Tasks Every ToolTalk-aware Application Needs to Perform</title>
<para>There are a number of tasks every ToolTalk-aware application needs to
perform, including:
</para>
<itemizedlist>
<listitem>
<para>Initializing the toolkit.
</para>
</listitem>
<listitem>
<para>Joining a ToolTalk session and registering patterns.
</para>
</listitem>
<listitem>
<para>Adding the ToolTalk service to its event loop.
</para>
</listitem>
</itemizedlist>
<para>This section provides examples of the ToolTalk code you need to include
in your application so that it can perform these tasks.
</para>
<Sect3 Id="TTUG.HTU.div.20">
<title>Initializing the Toolkit</title>
<indexterm><primary>toolkit initialization</primary></indexterm>
<para>Your application needs to initialize and register with the initial
ToolTalk session. To do so, it first needs to obtain a process
identifier (procid). The following code fragment shows how to obtain a
procid and how to initialize the toolkit.
</para>
<programlisting>char *procid = ttdt_open(
            int        *tt_fd,
            const char *ptype_name,
            const char *vendor_name,
            const char *version,
            int        send_started)
</programlisting>
<note>
<para>Your application must call <function>ttdt_open</function> before any other ToolTalk
calls are made; otherwise, errors may occur.
</para>
</note>
</sect3>
<Sect3 Id="TTUG.HTU.div.21">
<title>Joining the ToolTalk Session and Registering Message Patterns</title>
<indexterm><primary>message patterns, registering</primary></indexterm>
<para>Before your application can receive messages, it must join a ToolTalk
session and register the message patterns that are to be matched. The
ttdt_session_join function registers patterns and default callbacks for
many standard desktop message interfaces.
</para>
<programlisting>Tt_pattern *sess_patt = ttdt_session_join(
            const char        *session_id,
            Ttdt_contract_cb  cb,
            Widget            shell,
            void              *client_data,
            int               join)
</programlisting>
<para>Note that if an application has ptypes installed, it will normally call
the function <function>ttmedia_ptype_declare</function> before calling <function>ttdt_session_join</function>.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.22">
<title>Adding the ToolTalk Service to Event Loop</title>
<para>Your application also needs to add the ToolTalk service to its event
loop. If the application is an Xt client, it would use <function>XtAppAddInput</function> as
follows:
</para>
<programlisting>XtAppAddInput (app_context,
            tt_fd(),
            (XtPointer) XtInputReadMask,
            tttk_Xt_input_handler,
            client_data)
</programlisting>
</sect3>
</sect2>
<Sect2 Id="TTUG.HTU.div.23">
<title>Tasks ToolTalk-aware Editor Applications Need to Perform</title>
<para>In addition to the duties described in the section &ldquo;Tasks Every
ToolTalk-aware Application Needs to Perform&rdquo; in this chapter,
ToolTalk-aware editor applications may also need to perform other tasks,
including:
</para>
<itemizedlist>
<listitem>
<para>Declaring a ptype.
</para>
</listitem>
<listitem>
<para>Writing a media load callback.
</para>
</listitem>
<listitem>
<para>Accepting a contract to handle a message.
</para>
</listitem>
<listitem>
<para>Replying when a request has been completed.
</para>
</listitem>
</itemizedlist>
<para>This section provides examples of the ToolTalk code you need to include
in your editor application so that it can perform these additional
tasks.
</para>
<Sect3 Id="TTUG.HTU.div.24">
<title>Declaring a Ptype</title>
<indexterm><primary>ptype, declaring</primary></indexterm>
<para>If an application has a ptype file that has been installed, the ptypes
need to be associated with the application. The convenience function for
declaring this association is ttmedia_ptype_declare:
</para>
<programlisting>Tt_status status = ttmedia_ptype_declare(
            char                 *ptype_name,
            int                  base_opnum,
            Ttmedia_load_pat_cb  cb,
            void                 *client_data,
            int                  declare)
</programlisting>
<para>The callback <function>cb</function> is invoked when the application is asked to service
a request supported by the ptype <symbol role="variable">ptype_name</symbol>.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.25">
<title>Writing a Media Load Pattern Callback</title>
<para>Before coding an editor application to include any ToolTalk functions,
you need to write a media load callback routine. This callback is
invoked when another application responds to your application's
<function>ttmedia_load</function> call.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.26">
<title>Accepting a Contract to Handle a Message</title>
<para>When an application receives a message in its <function>ttmedia_ptype_declare</function>
handler, it should call the following function to accept a contract to
handle the request.
</para>
<programlisting>Tt_pattern *desktop_patts = ttdt_message_accept (
            Tt_message        contract,
            Ttdt_contract_cb  cb,
            Widget            shell,
            void              *client_data,
            int               accept,
            int               send_status)
</programlisting>
</sect3>
<Sect3 Id="TTUG.HTU.div.27">
<title>Replying When Request Is Completed</title>
<para>After your application has completed the operation requested (for
example to edit a document), it must reply to the sending application.
The following function can be used to do the reply and to return the
edited contents of the text to the sender.
</para>
<programlisting>Tt_message msg = ttmedia_load_reply (
            Tt_message           contract,
            const unsigned char  *new_contents,
            int                  new_length,
            int                  reply_and_destroy)
</programlisting>
</sect3>
</sect2>
<Sect2 Id="TTUG.HTU.div.28">
<title>Optional Tasks ToolTalk-aware Editor Applications Can Perform</title>
<para>In addition to the tasks described in the section &ldquo;Tasks ToolTalk-aware
Editor Applications Need to Perform&rdquo; in this chapter, editor
applications can also perform other optional tasks such as tasks that
use desktop file interfaces to coordinate with other editors. This
section mentions some of the ToolTalk functions you need to include in
your editor application so that it can perform these optional tasks.
</para>
<Sect3 Id="TTUG.HTU.div.29">
<title>Requesting Modify, Revert, or Save Operations</title>
<para>The following functions can be used to request modify, revert, or save
operations:
</para>
<itemizedlist>
<listitem>
<para><function>ttdt_Get_Modified</function>
</para>
</listitem>
<listitem>
<para><function>ttdt_Revert</function>
</para>
</listitem>
<listitem>
<para><function>ttdt_Save</function>
</para>
</listitem>
</itemizedlist>
</sect3>
<Sect3 Id="TTUG.HTU.div.30">
<title>Notifying When a File Is Modified, Reverted, or Saved</title>
<para>The function <function>ttdt_file_event</function> can be used to notify other ToolTalk
applications that your application's file has been modified, has
reverted, or has been saved.
</para>
</sect3>
<Sect3 Id="TTUG.HTU.div.31">
<title>Quitting a File</title>
<para>The function <function>ttdt_file_quit</function> unregisters interest in ToolTalk events
about a file and destroys the associated pattern.
</para>
</sect3>
</sect2>
</sect1>
</chapter>