ttdt_file_request(library call)             ttdt_file_request(library call)




 NAME    [Toc]    [Back]
      ttdt_file_request - create and send a standard ToolTalk request about
      a file

 SYNOPSIS    [Toc]    [Back]
      #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    [Toc]    [Back]
      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    [Toc]    [Back]
      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.





                                    - 1 -       Formatted:  January 24, 2005






 ttdt_file_request(library call)             ttdt_file_request(library call)




      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    [Toc]    [Back]
      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    [Toc]    [Back]
      Tt/tttk.h - Tttttk(5), ttdt_Get_Modified(3), ttdt_Save(3),
      ttdt_Revert(3), ttdt_file_join(3).


                                    - 2 -       Formatted:  January 24, 2005