187 lines
6.7 KiB
Plaintext
187 lines
6.7 KiB
Plaintext
<!-- $XConsortium: m_accept.sgm /main/8 1996/08/30 14:29:32 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. -->
|
|
<![ %CDE.C.CDE; [<RefEntry Id="CDEMX.XCDI.MAN263.rsml.1">]]>
|
|
<![ %CDE.C.XO; [<RefEntry Id="XCDI.MAN263.rsml.1">]]>
|
|
<RefMeta>
|
|
<RefEntryTitle>ttdt_message_accept</RefEntryTitle>
|
|
<ManVolNum>library call</ManVolNum>
|
|
</RefMeta>
|
|
<RefNameDiv>
|
|
<RefName><Function>ttdt_message_accept</Function></RefName>
|
|
<RefPurpose>accept a contract to handle a ToolTalk request
|
|
</RefPurpose>
|
|
</RefNameDiv>
|
|
<RefSynopsisDiv>
|
|
<FuncSynopsis Remap="ANSI">
|
|
<FuncSynopsisInfo>#include <Tt/tttk.h>
|
|
</FuncSynopsisInfo>
|
|
<FuncDef>Tt_pattern <Function>*ttdt_message_accept</Function></FuncDef>
|
|
<ParamDef>Tt_message <Parameter>contract</Parameter></ParamDef>
|
|
<ParamDef>Ttdt_contract_cb <Parameter>cb</Parameter></ParamDef>
|
|
<ParamDef>Widget <Parameter>shell</Parameter></ParamDef>
|
|
<ParamDef>void *<Parameter>clientdata</Parameter></ParamDef>
|
|
<ParamDef>int <Parameter>accept</Parameter></ParamDef>
|
|
<ParamDef>int <Parameter>sendStatus</Parameter></ParamDef>
|
|
</FuncSynopsis>
|
|
</RefSynopsisDiv>
|
|
<RefSect1>
|
|
<Title>DESCRIPTION</Title>
|
|
<Para>The
|
|
<Function>ttdt_message_accept</Function> function
|
|
registers in the default session for
|
|
<SystemItem Class="Constant">TT_HANDLER</SystemItem>-addressed requests:
|
|
</Para>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para><Symbol Role="Message">Get_Geometry</Symbol>, <Symbol Role="Message">Set_Geometry</Symbol>, <Symbol Role="Message">Get_Iconified</Symbol>, <Symbol Role="Message">Set_Iconified</Symbol>, <Symbol Role="Message">Get_Mapped</Symbol>, <Symbol Role="Message">Set_Mapped</Symbol>, <Symbol Role="Message">Raise</Symbol>, <Symbol Role="Message">Lower</Symbol>, <Symbol Role="Message">Get_XInfo</Symbol></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Symbol Role="Message">Pause</Symbol>, <Symbol Role="Message">Resume</Symbol></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Symbol Role="Message">Quit</Symbol>, <Symbol Role="Message">Get_Status</Symbol></Para>
|
|
</ListItem>
|
|
</OrderedList>
|
|
<Para>If the
|
|
<Symbol Role="Variable">shell</Symbol> argument is not
|
|
<SystemItem Class="Constant">NULL</SystemItem>, the ToolTalk service
|
|
handles messages in (1) transparently;
|
|
otherwise, it treats them like messages in (3).
|
|
</Para>
|
|
<Para>If
|
|
<Symbol Role="Variable">shell</Symbol> is non-
|
|
<SystemItem Class="Constant">NULL</SystemItem> and
|
|
<Emphasis>cb</Emphasis> is
|
|
<SystemItem Class="Constant">NULL</SystemItem>, then
|
|
the ToolTalk service
|
|
handles messages in (2) transparently by passing
|
|
<Symbol Role="Variable">shell</Symbol> and the appropriate boolean value to
|
|
<Function>XtSetSensitive</Function>(3). If
|
|
<Emphasis>cb</Emphasis> is
|
|
<SystemItem Class="Constant">NULL</SystemItem>, then
|
|
the ToolTalk service
|
|
treats messages in (2) like (3).
|
|
</Para>
|
|
<Para>If
|
|
<Emphasis>cb</Emphasis> is not
|
|
<SystemItem Class="Constant">NULL</SystemItem>, <Function>ttdt_message_accept</Function> passes messages in (3) to the
|
|
<Emphasis>cb</Emphasis> callback; otherwise it fails with
|
|
<SystemItem Class="Constant">TT_DESKTOP_ENOTSUP</SystemItem>.</Para>
|
|
<Para>If
|
|
<Emphasis>accept</Emphasis> is True,
|
|
<Function>ttdt_message_accept</Function> calls
|
|
&cdeman.tt.message.accept; with a
|
|
<Emphasis>contract</Emphasis> argument.
|
|
If
|
|
<Emphasis>contract</Emphasis> has a returned value from
|
|
<Function>tt_message_status</Function> of
|
|
<SystemItem Class="Constant">TT_WRN_START_MESSAGE</SystemItem>, it is the message that caused the tool to be started.
|
|
The tool should join any scopes it wants to serve before accepting
|
|
<Emphasis>contract</Emphasis>, so that it will receive any other messages already dispatched to its
|
|
ptype.
|
|
Otherwise, those messages will cause other instances of the
|
|
ptype
|
|
to be started.
|
|
If that is in fact desired (for example,
|
|
because the tool can only service one message at a time), then
|
|
the tool should undeclare its
|
|
ptype
|
|
while it is busy.
|
|
</Para>
|
|
<Para>If
|
|
<Emphasis>sendStatus</Emphasis> is True,
|
|
<Function>ttdt_message_accept</Function> sends a
|
|
<Symbol Role="Message">Status</Symbol> notice to the requester, using the
|
|
arguments (if any) passed to
|
|
<Function>ttdt_open</Function>.</Para>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>RETURN VALUE</Title>
|
|
<Para>Upon successful completion, the
|
|
<Function>ttdt_message_accept</Function> function
|
|
returns a null-terminated array of
|
|
<StructName Role="typedef">Tt_pattern</StructName>, and associates this array with
|
|
<Emphasis>contract</Emphasis>; otherwise, it returns an error pointer.
|
|
The application can use
|
|
&cdeman.tt.ptr.error; to extract one of the following
|
|
<StructName Role="typedef">Tt_status</StructName> values from the returned handle:
|
|
</Para>
|
|
<VariableList>
|
|
<VarListEntry>
|
|
<Term>TT_ERR_NOMP</Term>
|
|
<ListItem>
|
|
<Para>The
|
|
&cdeman.ttsession; process is not running and the ToolTalk service cannot restart it.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>TT_ERR_POINTER</Term>
|
|
<ListItem>
|
|
<Para>The pointer passed does not point to an object
|
|
of the correct type for this operation.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>TT_ERR_UNIMP</Term>
|
|
<ListItem>
|
|
<Para>The
|
|
&cdeman.ttsession; for the default session is of a version that does not support
|
|
<Function>tt_message_accept</Function>. If
|
|
<Emphasis>contract</Emphasis> is a
|
|
<SystemItem Class="Constant">TT_WRN_START_MESSAGE</SystemItem>, messages to the tool's
|
|
ptype
|
|
will remain blocked until
|
|
<Emphasis>contract</Emphasis> is rejected, replied to, or failed.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
</VariableList>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>APPLICATION USAGE</Title>
|
|
<Para>The
|
|
<Function>ttdt_message_accept</Function> function
|
|
is what a tool calls when it wants to accept responsibility for
|
|
handling (that is, failing or rejecting) a request.
|
|
</Para>
|
|
<Para>If
|
|
<Emphasis>contract</Emphasis> is destroyed by
|
|
&cdeman.tttk.message.destroy;, then the patterns will also be destroyed.
|
|
Otherwise, the caller
|
|
is responsible for iterating over the array and destroying each
|
|
pattern.
|
|
</Para>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>EXAMPLES</Title>
|
|
<Para>See
|
|
&cdeman.ttdt.session.join; for an example of a
|
|
<StructName Role="typedef">Ttdt_contract_cb</StructName> callback that can be used with
|
|
<Function>ttdt_message_accept</Function>.</Para>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>SEE ALSO</Title>
|
|
<Para>&cdeman.Tt.tttk.h;,
|
|
&cdeman.ttdt.open;,
|
|
&cdeman.ttmedia.ptype.declare;,
|
|
&cdeman.tt.ptype.declare;,
|
|
&cdeman.ttdt.session.join;,
|
|
&cdeman.ttdt.file.join;,
|
|
<![ %CDE.C.CDE;[&cdeman.tt.ptype.undeclare;,
|
|
<Function>XtSetSensitive</Function>(3). ]]><![ %CDE.C.XO;
|
|
[&cdeman.tt.ptype.undeclare;;
|
|
<Function>XtSetSensitive</Function> in the &str-Zt;.
|
|
]]>
|
|
</Para>
|
|
</RefSect1>
|
|
</RefEntry>
|
|
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:18:47-->
|