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:

    The ToolTalk service could not access the ToolTalk database needed for this operation.
    The ToolTalk service could not access the specified ToolTalk database in the expected place.
    There is insufficient memory available to perform the function.
    The ttsession(1) process is not running and the ToolTalk service cannot restart it.
    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.)
    The pathname argument was NULL or was a ToolTalk error pointer.
    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).