.TH "globus_gass_transfer_server" 3 "Version 9.4" "globus_gass_transfer" \" -*- nroff -*- .ad l .nh .SH NAME globus_gass_transfer_server \- Implementing Servers .PP \- GASS Server Implementation\&. .SH SYNOPSIS .br .PP .SS "Typedefs" .in +1c .ti -1c .RI "typedef void(* \fBglobus_gass_transfer_close_callback_t\fP) (void *callback_arg, globus_gass_transfer_listener_t listener)" .br .ti -1c .RI "typedef void(* \fBglobus_gass_transfer_listen_callback_t\fP) (void *callback_arg, globus_gass_transfer_listener_t listener)" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "int \fBglobus_gass_transfer_create_listener\fP (globus_gass_transfer_listener_t *listener, globus_gass_transfer_listenerattr_t *attr, char *scheme)" .br .ti -1c .RI "int \fBglobus_gass_transfer_close_listener\fP (globus_gass_transfer_listener_t listener, \fBglobus_gass_transfer_close_callback_t\fP callback, void *user_arg)" .br .ti -1c .RI "int \fBglobus_gass_transfer_register_listen\fP (globus_gass_transfer_listener_t listener, \fBglobus_gass_transfer_listen_callback_t\fP callback, void *user_arg)" .br .ti -1c .RI "int \fBglobus_gass_transfer_register_accept\fP (\fBglobus_gass_transfer_request_t\fP *request, globus_gass_transfer_requestattr_t *attr, globus_gass_transfer_listener_t listener, globus_gass_transfer_callback_t callback, void *user_arg)" .br .ti -1c .RI "void * \fBglobus_gass_transfer_listener_get_user_pointer\fP (globus_gass_transfer_listener_t listener)" .br .ti -1c .RI "int \fBglobus_gass_transfer_listener_set_user_pointer\fP (globus_gass_transfer_listener_t listener, void *user_pointer)" .br .ti -1c .RI "char * \fBglobus_gass_transfer_listener_get_base_url\fP (globus_gass_transfer_listener_t listener)" .br .ti -1c .RI "int \fBglobus_gass_transfer_refer\fP (\fBglobus_gass_transfer_request_t\fP request, char **urls, globus_size_t num_urls)" .br .ti -1c .RI "int \fBglobus_gass_transfer_authorize\fP (\fBglobus_gass_transfer_request_t\fP request, globus_size_t total_length)" .br .ti -1c .RI "int \fBglobus_gass_transfer_deny\fP (\fBglobus_gass_transfer_request_t\fP request, int reason, char *message)" .br .in -1c .SH "Detailed Description" .PP GASS Server Implementation\&. Implementing Servers .PP Another mode of using the GASS Transfer API is to implement data servers\&. The primary difference between the client and server parts of the GASS Transfer API are how requests are generated\&. .PP To implement a server, the user would call \fBglobus_gass_transfer_create_listener()\fP to create a new server port on which a specific protocol will be used to request file transfer operations\&. The user may obtain the URL that the listener is bound to by calling \fBglobus_gass_transfer_listener_get_base_url()\fP\&. .PP Once the listener is created, the user can call \fBglobus_gass_transfer_register_listen()\fP to wait for clients to connect to it\&. Once the server has detected an attempt to connect by a client, the use can call \fBglobus_gass_transfer_register_accept()\fP to accept the connection from the client and parse the request\&. .PP In the callback associated with \fBglobus_gass_transfer_register_accept()\fP, the server can decide how to process the request\&. The user may choose to authorize the request by calling \fBglobus_gass_transfer_authorize()\fP, refer it to another URL or URLs by calling \fBglobus_gass_transfer_refer()\fP or deny the client access to the URL by calling \fBglobus_gass_transfer_deny()\fP\&. .SH "Typedef Documentation" .PP .SS "typedef void(* globus_gass_transfer_close_callback_t) (void *callback_arg, globus_gass_transfer_listener_t listener)" Listener close callback .PP \fBParameters\fP .RS 4 \fIcallback_arg\fP .br \fIlistener\fP .RE .PP .SS "typedef void(* globus_gass_transfer_listen_callback_t) (void *callback_arg, globus_gass_transfer_listener_t listener)" Listen callback\&. .PP \fBParameters\fP .RS 4 \fIcallback_arg\fP .br \fIlistener\fP .RE .PP .SH "Function Documentation" .PP .SS "int globus_gass_transfer_authorize (\fBglobus_gass_transfer_request_t\fP request, globus_size_t total_length)" Authorize a request\&. .PP This function causes the request to be authorized for processing\&. It should be called in response to a request accept callback when the server wants to agree to process this request\&. After calling this function, the server implementation should call \fBglobus_gass_transfer_send_bytes()\fP or \fBglobus_gass_transfer_receive_bytes()\fP to send or receive the data associated with the URL\&. .PP \fBParameters\fP .RS 4 \fIrequest\fP A new request handle, passed to the server in an accept callback\&. .br \fItotal_length\fP For a 'get' request, the total_length of the file to be retrieved if known\&. This value may be GLOBUS_GASS_LENGTH_UNKNOWN if the protocol supports transferring arbitrarily-sized files\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_GASS_TRANSFER_ERROR_INVALID_USE\fP The request handle was not valid, not created by calling \fBglobus_gass_transfer_register_accept()\fP, or has already been denied or authorized\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_NOT_IMPLEMENTED\fP The protocol module does not support authorizing requests\&. .RE .PP \fBSee also\fP .RS 4 \fBglobus_gass_transfer_refer()\fP, \fBglobus_gass_transfer_deny()\fP .RE .PP .SS "int globus_gass_transfer_close_listener (globus_gass_transfer_listener_t listener, \fBglobus_gass_transfer_close_callback_t\fP callback, void * user_arg)" Close a GASS listener\&. .PP This function calls the protocol specific function needed to close a GASS server listener port\&. Callbacks for any outstanding accepts will be called before the close callback is invoked\&. .PP \fBParameters\fP .RS 4 \fIlistener\fP Listener handle created by calling \fBglobus_gass_transfer_create_listener()\fP\&. .br \fIcallback\fP Function to call once the listener handle has been closed\&. .br \fIuser_arg\fP Argument to be passed to the \fIcallback\fP function\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_SUCCESS\fP The close operation was successfully registered on the listener\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_INVALID_USE\fP The listener handle was invalid\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_NOT_INITIALIZED\fP The listener handle was not properly initialized\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_DONE\fP A close has already been registered on the listener\&. .RE .PP .SS "int globus_gass_transfer_create_listener (globus_gass_transfer_listener_t * listener, globus_gass_transfer_listenerattr_t * attr, char * scheme)" Create a new protocol-specific listener socket for a GASS server\&. .PP This function creates a new socket to listen for client connections as a GASS server\&. The listener handle pointer is initialized to contain the a new handle which can be used in subsequent server operations\&. .PP After calling this function, a user may call the \fBglobus_gass_transfer_register_listen()\fP or \fBglobus_gass_transfer_close_listener()\fP functions with this listener handle\&. .PP \fBParameters\fP .RS 4 \fIlistener\fP A new listener handle to initialize\&. .br \fIattr\fP Protocol-specific attributes for the new listener\&. .br \fIscheme\fP The protocol scheme to implement for the listener\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_SUCCESS\fP The listener was successfully created\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_NULL_POINTER\fP The \fIlistener\fP or \fIscheme\fP parameter was NULL .br \fIGLOBUS_GASS_TRANSFER_ERROR_NOT_IMPLEMENTED\fP The \fIscheme\fP is not supported by any protocol module\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_MALLOC_FAILED\fP Data structures associated with the transfer could not be allocated\&. .RE .PP .SS "int globus_gass_transfer_deny (\fBglobus_gass_transfer_request_t\fP request, int reason, char * message)" Deny a request\&. .PP This function causes the request to be denied for further processing\&. It should be called in response to a request ccept callback when the server wants to refuse processing this request for the client\&. After calling this function, the server implementation need do nothing further with the request handle\&. .PP \fBParameters\fP .RS 4 \fIrequest\fP A new request handle, passed to the server in an accept callback\&. .br \fIreason\fP A protocol-specific reason code\&. .br \fImessage\fP An informational message to be sent to the client\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_GASS_TRANSFER_ERROR_INVALID_USE\fP The request handle was not valid, not created by calling \fBglobus_gass_transfer_register_accept()\fP, or has already been denied or authorized\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_NOT_IMPLEMENTED\fP The protocol module does not support denying requests\&. .RE .PP \fBSee also\fP .RS 4 \fBglobus_gass_transfer_refer()\fP, \fBglobus_gass_transfer_authorize()\fP .RE .PP .SS "char * globus_gass_transfer_listener_get_base_url (globus_gass_transfer_listener_t listener)" Get the base URL of a listener\&. .PP This function queries a listener handle for the base URL which the server is listening on\&. For most protocols, this contains the protocol scheme, host, and port that the listener has registered itself on\&. .PP \fBParameters\fP .RS 4 \fIlistener\fP The listener handle to query\&. .RE .PP \fBReturns\fP .RS 4 This function returns a pointer to a string containing the base URL\&. This string must not be freed or modified by the caller\&. It may not be referred to after the function globus_gass_transfer_listener_close() has been called\&. .RE .PP .SS "void * globus_gass_transfer_listener_get_user_pointer (globus_gass_transfer_listener_t listener)" Get the user pointer associated with a listener\&. .PP This function will query the listener's user_pointer field and return it's value\&. .PP \fBParameters\fP .RS 4 \fIlistener\fP The listener handle\&. .RE .PP \fBReturns\fP .RS 4 If the listener handle is invalid or the user_pointer's value has not been set, then GLOBUS_NULL will be returned\&. Otherwise, the value of the user pointer will be returned\&. .RE .PP \fBSee also\fP .RS 4 \fBglobus_gass_transfer_listener_set_user_pointer()\fP .RE .PP .SS "int globus_gass_transfer_listener_set_user_pointer (globus_gass_transfer_listener_t listener, void * user_pointer)" Set the user pointer associated with a listener\&. .PP This function will set the listener's user_pointer field\&. The pointer may be used to associate any pointer-sized data with a listener handle\&. .PP \fBParameters\fP .RS 4 \fIlistener\fP The listener handle\&. .br \fIuser_pointer\fP The value of the user pointer\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_SUCCESS\fP The user pointer was successfully set\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_INVALID_USE\fP The \fIlistener\fP handle was invalid\&. .RE .PP \fBSee also\fP .RS 4 \fBglobus_gass_transfer_listener_get_user_pointer()\fP .RE .PP .SS "int globus_gass_transfer_refer (\fBglobus_gass_transfer_request_t\fP request, char ** urls, globus_size_t num_urls)" Refer a request\&. .PP This function causes the request to be referred to another URL or list of URLs\&. It should be called in response to a request accept callback when the server wants to refer the client to another server or servers to process the request\&. .PP \fBParameters\fP .RS 4 \fIrequest\fP A new request handle, passed to the server in an accept callback\&. .br \fIurls\fP An array of strings, each being a URL pointing to sources of the same data as the original URL\&. .br \fInum_urls\fP The length of the \fIurls\fP array\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_GASS_TRANSFER_ERROR_INVALID_USE\fP The request handle was not valid, not created by calling \fBglobus_gass_transfer_register_accept()\fP, or has already been denied or authorized\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_NOT_IMPLEMENTED\fP The protocol module does not support referrals\&. .RE .PP \fBSee also\fP .RS 4 \fBglobus_gass_transfer_deny()\fP, \fBglobus_gass_transfer_authorize()\fP .RE .PP .SS "int globus_gass_transfer_register_accept (\fBglobus_gass_transfer_request_t\fP * request, globus_gass_transfer_requestattr_t * attr, globus_gass_transfer_listener_t listener, globus_gass_transfer_callback_t callback, void * user_arg)" Accept new client connections\&. .PP This function causes the listener handle to accept a new connection on the listener and parse the file request\&. Once the file request has been parsed, the specified \fIcallback\fP function will be called\&. The server implementation must then either authorize, deny, or refer this request\&. .PP \fBParameters\fP .RS 4 \fIrequest\fP A pointer to a new request handle\&. This request handle will be initialized when the callback function is invoked\&. .br \fIattr\fP Request attributes\&. .br \fIlistener\fP The listener handle to register for the new request\&. .br \fIcallback\fP Function to call when the protocol module has parsed the file request\&. .br \fIuser_arg\fP Argument to be passed to the callback function\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_SUCCESS\fP The listen callback has been registered with the protocol module\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_INVALID_USE\fP An invalid \fIlistener\fP handle was passed to this function\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_NOT_INITIALIZED\fP An uninitialized \fIlistener\fP handle was passed to this function\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_INTERNAL_ERROR\fP The request could not be initialized due to some internal resource depletion\&. .br \fIGLOBUS_GASS_NOT_REGISTERED\&.\fP The \fBglobus_gass_transfer_register_listen()\fP function has not yet been called\&. .br \fIGLOBUS_GASS_ALREADY_REGISTERED\&.\fP The listener is already processing a new request\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_DONE\fP The listener has been registered for closing\&. .RE .PP \fBSee also\fP .RS 4 \fBglobus_gass_transfer_register_listen()\fP; .RE .PP .SS "int globus_gass_transfer_register_listen (globus_gass_transfer_listener_t listener, \fBglobus_gass_transfer_listen_callback_t\fP callback, void * user_arg)" Listen for new client connections\&. .PP This function causes the listener handle to listen for new client connections\&. When one is ready, it calls the specified \fIcallback\fP function, letting the server implementer continue to accept the connection and process the request\&. .PP \fBParameters\fP .RS 4 \fIlistener\fP The listener handle to register for new connections\&. .br \fIcallback\fP Function to call when a new connection may be accepted\&. .br \fIuser_arg\fP Argument to be passed to the callback function\&. .RE .PP \fBReturn values\fP .RS 4 \fIGLOBUS_SUCCESS\fP The listen callback has been registered with the protocol module\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_INVALID_USE\fP An invalid \fIlistener\fP handle was passed to this function\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_NOT_INITIALIZED\fP An uninitialized \fIlistener\fP handle was passed to this function\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_ALREADY_REGISTERED\fP The listener has already been registered for a new connection\&. .br \fIGLOBUS_GASS_TRANSFER_ERROR_DONE\fP The listener has been registered for closing\&. .RE .PP \fBSee also\fP .RS 4 \fBglobus_gass_transfer_register_accept()\fP; .RE .PP .SH "Author" .PP Generated automatically by Doxygen for globus_gass_transfer from the source code\&.