ttdt_file_request(3)

NAME
     ttdt_file_request - create and send a standard ToolTalk request about a
     file

SYNOPSIS
     #include <Tt/tttk.h>
     Tt_message ttdt_file_request(Tt_message context,
                                  Tttk_op op,
                                  Tt_scope scope,
                                  const char *pathname,
                                  Ttdt_file_cb cb,
                                  void *client_data,
                                  int send_and_destroy);

DESCRIPTION
     The ttdt_file_request() function is used to create (and optionally send)
     any of the standard Desktop file requests such as Get_Modified, Save, and
     Revert.

     The ttdt_file_request() function creates a request with the specified op
     and scope, and sets its file attribute to pathname.  The function adds an
     unset argument of Tt_mode TT_IN and vtype File to the request, per the
     Desktop messaging conventions.  If op is TTDT_GET_MODIFIED,
     ttdt_file_request() also adds an unset TT_OUT argument of vtype Boolean
     to the request.  The ttdt_file_request() function installs cb as a
     message callback for the created request, and ensures that client_data
     will be passed into the callback.  (The Ttdt_file_cb callback is
     described under ttdt_file_join(3)).  If send is True, ttdt_file_request()
     sends the request before returning the handle to it; otherwise, it only
     creates the request.

     The context argument describes the environment to use.  If context is not
     zero, messages created by ttdt_file_request() inherit from context all
     contexts whose slotname begins with the characters ENV_.

RETURN VALUE
     Upon successful completion, the ttdt_file_request() function returns the
     created Tt_message; otherwise, it returns an error pointer.  The
     application can use tt_ptr_error(3) to extract one of the following
     Tt_status values from the returned handle:

        TT_ERR_DBAVAIL
                The ToolTalk service could not access the ToolTalk database
                needed for this operation.

        TT_ERR_DBEXIST
                The ToolTalk service could not access the specified ToolTalk
                database in the expected place.
        TT_ERR_NOMEM
                There is insufficient memory available to perform the
                function.

        TT_ERR_NOMP
                The ttsession(1) process is not running and the ToolTalk
                service cannot restart it.

        TT_ERR_OVERFLOW
                The ToolTalk service has more active messages than it can
                handle.  (The maximum number of active messages is
                implementation specific, but is at least 2000.)

        TT_ERR_POINTER
                The pathname argument was NULL or was a ToolTalk error
                pointer.

        TT_ERR_PROCID
                The specified process identifier is out of date or invalid.

APPLICATION USAGE
     The ttdt_file_request() function is a lower-level interface than
     ttdt_Get_Modified(), ttdt_Save(), and ttdt_Revert(), since the latter
     functions create and send the request and then block on its reply.

SEE ALSO
     Tttttk(5), ttdt_Get_Modified(3), ttdt_Save(3), ttdt_Revert(3),
     ttdt_file_join(3).