Defining Process Types

Your application can still be considered a potential message receiver even when no process is running the application. To do this, you provide message patterns and instructions on how to start the application in a process type (ptype) file. These instructions tell the ToolTalk service to perform one of the following actions when a message is available for an application but the application is not running:

Start the application and deliver the message
Queue the message until the application is running
Discard the message

To make the information available to the ToolTalk service, the ptype file is compiled with the ToolTalk type compiler, tt_type_comp, at application installation time.

When an application registers a ptype with the ToolTalk service, the message patterns listed in it are automatically registered, too.

Ptypes provide application information that the ToolTalk service can use when the application is not running. This information is used to start your process if necessary to receive a message or queue messages until the process starts.

A ptype begins with a process-type identifier (ptid). Following the ptid are:

An optional start string — The ToolTalk service will execute this command, if necessary, to start a process running the program.
Signatures — Describes the TT_PROCEDURE-addressed messages that the program wants to receive. Messages to be observed are described separately from messages to be handled.

Signatures

Signatures describe the messages that the program wants to receive. A signature is divided by an arrow (=>) into two parts. The first part of a signature specifies matching attribute values. The more attribute values specified in a signature, the fewer messages the signature will match. The second part of a signature specifies receiver values that the ToolTalk service will copy into messages that match the first part of the signature.

A ptype signature can contain values for disposition and operation numbers (opnum). The ToolTalk service uses the disposition value (start, queue, or the default discard) to determine what to do with a message that matches the signature when no process is running the program. The opnum value is provided as a convenience to message receivers. When two signatures have the same operation name but different arguments, different opnums makes incoming messages easy to identify.

Creating a Ptype File

The following listing illustrates a ptype file.

#include "Sun_EditDemo_opnums.h"

ptype Sun_EditDemo {
        /* setenv Sun_EditDemo_HOME to install dir for the demo */
     start    “${Sun_EditDemo_HOME}/edit”;
     handle:
     /* edit file named in message, start editor if necessary */
     session Sun_EditDemo_edit(void)
                    => start opnum=Sun_EditDemo_EDIT;

     /* tell editor viewing file in message to save file */
     session Sun_EditDemo_save(void)
                    => opnum=Sun_EditDemo_SAVE;

     /* save file named in message to new filename */
     session Sun_EditDemo_save_as(in string new_filename)
                    => opnum=Sun_EditDemo_SAVE_AS;

     /* bring down editor viewing file in message */
     session Sun_EditDemo_close(void)
                    => opnum=Sun_EditDemo_CLOSE;
};

The following listing shows the syntax for a ptype file.

ptype    ::=    'ptype' ptid `{'
        property^*        [`observe:' psignature^*]
        [`handle:' psignature^* ]
        [`handle_push:' psignature^*]
        [`handle_rotate:' psignature^*]
        `}' [`;']
property    ::=    property_id value `;'
property_id    ::=    `start'
value    ::=    string
ptid    ::=    identifier
psignature    ::=    [scope] op args [contextdcl]
        [`=>'
        [`start'][`queue']
        [`opnum='number]]
        `;'
scope    ::=    `file'
    |    `session'
    |    `file_in_session'
args    ::=    `(` argspec {, argspec}^* `)'
    |    `(void)'
    |    `()'
contextdcl    ::=    `context' `(` identifier {, identifier}* `)' `;'
argspec    ::=    mode type name
mode    ::=    `in' | `out' | `inout'
type    ::=    identifier
name    ::=    identifier

Property_id Information

ptid—process type identifier (ptid). Identifies the process type. A ptid must be unique for every installation. Because this identifier cannot be changed after installation time, each chosen name must be unique. For example, you can use a name that includes the trademarked name of your product or company, such as Sun_EditDemo. The ptid cannot exceed 32 characters and should not be one of the reserved identifiers: ptype, otype, start, opnum, queue, file, session, observe, or handle.

start—start string for the process. If the ToolTalk service needs to start a process, it executes this command; /bin/sh is used as the shell.

Before executing the command, the ToolTalk service defines TT_FILE as an environment variable with the value of the file attribute of the message that started the application. This command runs in the environment of ttsession, not in the environment of the sender of the message that started the application, so any context information must be carried by message arguments or contexts.

Psignature Matching Information

scope—this pattern attribute is matched against the scope attribute in messages.

op—operation name. This name is matched against the op attribute in messages.

Note - If you specify message signatures in both your ptype and otypes, use unique operation names in each. For example, do not specify a display operation in both your ptype and otype.

args—arguments for the operation. If the args list is void, the signature matches only messages with no arguments. If the args list is empty (that is, “()”), the signature matches without regard to the arguments.

contextdcl—context name. When a pattern with this named context is generated from the signature, it contains an empty value list.

Psignature Actions Information

start—if the psignature matches a message and no running process of this ptype has a pattern that matches the message, start a process of this ptype.

queue—if the psignature matches a message and no running process of this ptype has a pattern that matches the message, queue the message until a process of this ptype registers a pattern that matches it.

opnum—fill in the message's opnum attribute with the specified number to enable you to identify the signature that matched the message.

When the message matches the signature, the opnum from the signature is filled into the message. Your application can then retrieve the opnum with the tt_message_opnum call. By giving each signature a unique opnum, you can quickly determine which signature matched the message.

You can attach a callback routine to the opnum with the tt_ptype_opnum_callback_add call. When the message is matched, the ToolTalk service will check for any callbacks attached to the opnum and, if any are found, run them.

The Sun_EditDemo_opnums.h file defines symbolic definitions for all the opnums used by edit.c, allowing both the edit.types file and edit.c file to share the same definitions.

Automatically Starting a Tool

The listing below is a simple example of a ptype declaration that causes the ToolTalk service to automatically start a tool. The example code states:

If a message to display, edit, or compose is received and there is no current instance of the tool running that can handle the message, start “/home/toone/tools/mytest” and deliver the message.

Caution - This example causes the ToolTalk service to search indefinitely for a handler.

ptype My_Test {
    start "/home/toone/tools/mytest";
    handle:

    session Display (in Ascii text) => start;
    session Edit (inout Ascii text) => start;
    session Compose (out Ascii text) => start;

    file Display (in Ascii file_name) => start;
    file Edit (inout Ascii file_name) => start;
    file Compose (out Ascii file_name) => start;
};