pyGlobus.ftpControl.FtpControl

Package pyGlobus :: Module ftpControl :: Class FtpControl

[show private | hide private]

Class FtpControl

Class that wraps a ftpControl handle, a structure which contains the logic for a globus ftp serve

Method Summary
	`__init__(self, handle)` Constructs an instance.
	`__del__(self)` Deletes the instance and frees the memory associated with the handle
	`abort(self, callback, arg)` Send an ABORT to the FTP server and register a response handler
	`authenticate(self, auth_info, use_auth, callback, arg)` authenticate the user to the FTP server
	`code(self, command)` Retreives a command code from a globus ftp control command.
	`control_connect(self, host, port, callback, arg)` Create a new control connectiong to an FTP server.
	`create_data_info(self, buffer, offset, eof, callback, arg)` Creates a write_info data structure,
	`data_add_channels(self, num_channels, stripe_ndx)` Opens additional data channels (connections) to the host identified by the stripe parameter
	`data_connect(self, callback, arg)` Create an outgoing FTP data connection.
	`data_connect_read(self, callback, arg)` Create an incoming FTP data connection
	`data_query_channels(self, stripe_ndx)` Returns the number of currently open channels for the host identified by the stripe parameter
	`data_read(self, buffer, callback, arg)` Reads data from data connection(s) and puts it in the specified buffer.
	`data_remove_channels(self, num_channels, stripe_ndx)` Removes data channels, to the host identified by the stripe parameter
	`data_send_eof(self, eof_array, eof, callback, arg)` Sends an eof message to each stripe along an open data connection
	`data_write(self, buffer, offset, eof, callback, arg)` Writes data from the supplied buffer to data connection(s)
	`data_write_stripe(self, buffer, offset, eof, stripe_ndx, callback, arg)` Writes data to the specified stripe
	`force_close(self, callback, arg)` Force a close of the control connection without sending a QUIT or waiting for outstanding commands to complete
	`free_callbackData(self, callbackHandle)` Frees the memory associated with the callback handle
	`free_callbackDefault(self, callbackHandle)` Frees the memory associated with the callback handle
	`get_handle(self)` Gets a pointer to the handle.
	`get_pbsz(self)` Return the size of the protection buffer size information
	`get_total_data_channels(self, stripe_ndx)` Returns the number of data channels used so far on this particular stripe
	`local_dcau(self, dcau, credential)` Channel authentication.
	`local_mode(self, mode)` Update the ftp handle with the given mode information
	`local_parallelism(self, parallelism)` Set the parallelism information in a FTP control handle
	`local_pasv(self)` Create a local listening socket, bind it and return the address the socket is listening to.
	`local_pbsz(self, size)` Update the ftp handle with the given protection buffer size information
	`local_port(self, address)` Insert the host/port information returned by a PASV on the remote host into the local FTP control handle.
	`local_send_eof(self, eof)` Determines if the library will automatically send an EOF message in extended block mode, or if the user will have to explicity do it by calling data_send_eof
	`local_spas(self, address_array)` Striped Passive -- enables parallelism and striping
	`local_spor(self, address_array)` Striped Port -- enables parallelism and striping Insert the host/port addresses returned by a SPOR on the remote host into the local FTP control handle.
	`local_stru(self, structure)` Update the handle information on the structure of the data being sent on the data channel
	`local_tcp_buffer(self, tcp_buffer)` Update the ftp handle with the given socket buffer size information
	`local_type(self, dataType)` Update the FTP control handle with the given type information.
	`operation(self, command)` Retrieves the operation associated with a globus ftp control command.
	`quit(self, callback, arg)` send a QUIT to the FTP server and register a response handler
	`raw_command(self, command)` Retrieves a raw command from a globus ftp control command.
	`read_commands(self, callback, arg)` Begin reading GSIFTP commands.
	`release_data_info(self, write_info)` Releases the memory associated with the write_info object Must be called after each create_data_info call
	`send_command(self, cmdspec, callback, arg)` send a command to the FTP server and register a response handler
	`send_response(self, resp, callback, arg)` Send a response to the GSIFTP client.
	`x_data_write_stripe(self, buffer, offset, eof, stripe_ndx, write_info)` Writes data to the specified stripe

Method Details

init(self, handle=None)
(Constructor)

Constructs an instance.

Activates the underlying GLOBUS_FTP_CONTROL_MODULE

Parameters:: handle - a SWIG'ized pointer to a globus ftp control handle object

Returns:: None

Raises:: FtpControlException - A FtpControlException is raised if the globus module cannot be activated or the handle cannot be initialized.

del(self)
(Destructor)

Deletes the instance and frees the memory associated with the handle

Returns:: None

Raises:: FtpControlException - A FtpControlException is raised if the globus module cannot be deactivated or the handle cannot be freed.

abort(self, callback, arg)

Send an ABORT to the FTP server and register a response handler

Parameters:: callback - a Python function that has the signature func(user_arg,handle, error, ftp_response); arg - the user_arg to the callback function

Returns:: returns a SWIG'ized callback handle
Raises FtpControlException if the ABORT message could not be sent

authenticate(self, auth_info, use_auth, callback, arg)

authenticate the user to the FTP server

Parameters:: auth_info - a Python object which wraps a globus_auth_info object; use_auth - a boolean which if true GSS authentication will be used, otherwise username, password authentication will be used; callback - a Python function that has the signature func(user_arg,handle, error, ftp_response); arg - the user_arg to the callback function

Returns:: Returns a SWIG'ized callback handle

Raises:: FtpControlException - A FtpControlException if the command could not be sent

code(self, command)

Retreives a command code from a globus ftp control command.

Parameters:: command - The globus command to be assessed..

Returns:: The code corresponding with the command.
None

control_connect(self, host, port, callback, arg)

Create a new control connectiong to an FTP server.

Parameters:: host - the hostname on a FTP Server; port - the TCP port number on a FTP Server; callback - a Python function that has the signature func(user_arg,handle, error, ftp_response); arg - the user_arg to the callback function

Returns:: returns a SWIG'ized callback handle

Raises:: FtpControlException - A FtpControlException if a connection could not be initiated

create_data_info(self, buffer, offset, eof, callback, arg)

Creates a write_info data structure,

Parameters:: buffer - is a pyGlobus.util Buffer object; offset - file offset of the data specified; eof - boolean denoting whether an end of file has been reached; callback - a python function that has the signature func(user_arg, handle, error, buffer, length, offset, eof); arg - a user supplied arguement to the callback function

Returns:: Returns a SWIG'ized callback handle, and a SWIG'ized write_info pointer.

Raises:: FtpControlException - A FtpControlException if the write_info object could not be created.

data_add_channels(self, num_channels, stripe_ndx)

Opens additional data channels (connections) to the host identified by the stripe parameter

Parameters:: num_channels - The number of additional channels to add; stripe_ndx - The stripe that the channels will belong to

Returns:: None

Raises:: FtpControlException - A FtpControlException if the channels could not be added

data_connect(self, callback, arg)

Create an outgoing FTP data connection.

This function will register a globus_io_{accept, connect}. Further accepts/connects are done by registering a new accept/connect in the current accept/connect callback. A call to either local_pasv() or local_port() needs to precede this calling this function. This function may be followed by a globus_ftp_data_write.

Parameters:: callback -
A Python function to be called when the connection occurs. It has the following signature
'function(arg, handle, stripe_ndx, reuse, error)' where arg is the argument passed into this call, handle is a SWIG'ized pointer to a ftp control handle object, stripe_ndx is an int representing which strip the connect is associated with, reuse is a bool whose value is dependent on whether the connnection can be reused and error is a string containing 'NONE', or an error message.; arg - A user argument to be returned when the callback is executed.

Returns:: A SWIG'ized pointer to a callback handle

Raises:: FtpControlException - A FtpControlException is raised if there is a problem with the registering connection

data_connect_read(self, callback, arg)

Create an incoming FTP data connection

Parameters:: callback - a python function that has the signature: func(user_arg, handle, stripe_ndx, reuse, error); arg - the user_arg to the callback function

Returns:: Returns a SWIG'ized callback handle

Raises:: FtpControlException - A FtpControlException if the data connection could not be created

data_query_channels(self, stripe_ndx)

Returns the number of currently open channels for the host identified by the stripe parameter

Parameters:: stripe_ndx - The stripe that you wish to query

Returns:: number of channels on that stripe

Raises:: FtpControlException - A FtpControlException if the stripe could not be queried

data_read(self, buffer, callback, arg)

Reads data from data connection(s) and puts it in the specified buffer.

Parameters:: buffer - Destination buffer- where the data gets written.; callback - a python function that has the signature func(user_arg, handle, error, buffer, length, offset, eof); arg - a user supplied arguement to the callback function

Returns:: Returns a SWIG'ized callback handle.

data_remove_channels(self, num_channels, stripe_ndx)

Removes data channels, to the host identified by the stripe parameter

Parameters:: num_channels - The number of additional channels to add; stripe_ndx - The stripe that the channels will belong to

Returns:: None

Raises:: FtpControlException - A FtpControlException if the channels could not be removed

data_send_eof(self, eof_array, eof, callback, arg)

Sends an eof message to each stripe along an open data connection

Parameters:: eof_array - a python argument which wraps an array of integers. The array of integers should contain an integer that will be added to the curretn parallel data connection count on each stripe. The order of the integers corresponds to th eeach stripe in the same order as what was returned from local_port(); eof - boolean which is the eof message to be sent to all of the channels specified in the eof array; callback - a function with the signature func(user_arg, handle, error); arg - the user_arg for the callback function

Returns:: returns a SWIG'ized callback handle

Raises:: FtpControlException - A FtpControlException if the eofs could not be sent

data_write(self, buffer, offset, eof, callback, arg)

Writes data from the supplied buffer to data connection(s)

This function writes contained in the buffer to the data channel(s).

Parameters:: buffer - A string of the data to be written out.; offset - An int which is the offset in the file at which the data in the buffer starts; eof - Indicates that the buffer is that last part of a file. In the striped case this will cause a EOF block to be send to every data node involved in the transfer.; callback -
A Python function to be called once the data has been sent. It has the following signature.
'function(arg, handle, bufHandle, bufLen, offset, eof)' where arg is the user argument passed into this call, handle is the underlying ftp_control handle, bufHandle is a SWIG'ized pointer to the underlying globus_byte_t array, bufLen is the length of the underlying globus_byte_t array, offset is the offset into the file this data block contains, and eof is a bool that is true if the end of the data transfer has been reached.; arg - A user argument to be passed through to the callback.

Returns:: A SWIG'ized pointer to the callback handle is returned. After the callback completes, this may be free'd with the free_callback method, or it will be free'd when the instance is destroyed.

Raises:: FtpControlException - A FtpControlException is thrown if unable to do the write.

data_write_stripe(self, buffer, offset, eof, stripe_ndx, callback, arg)

Writes data to the specified stripe

Parameters:: buffer - a string of the data to be written out; offset - the offset into file that has been written so far; eof - boolean flag if it is the last data to be written; stripe_ndx - the stripe which the data is written to.; callback - a python function that has the signature func(user_arg, handle, error, buffer, length, offset, eof); arg - a user supplied arguement to the callback function

Returns:: Returns a SWIG'ized callback handle

Raises:: FtpControlException - A FtpControlException if the data could not be written.

force_close(self, callback, arg)

Force a close of the control connection without sending a QUIT or waiting for outstanding commands to complete

Parameters:: callback - a Python function that has the signature func(user_arg,handle, error, ftp_response); arg - the user_arg to the callback function

Returns:: returns a SWIG'ized callback handle

Raises:: FtpControlException - A FtpControlException if the channel could not be closed

free_callbackData(self, callbackHandle)

Frees the memory associated with the callback handle

Parameters:: callbackHandle - - a SWIG'ized pointer to a callback handle

Returns:: None
None

free_callbackDefault(self, callbackHandle)

Frees the memory associated with the callback handle

Parameters:: callbackHandle - - a SWIG'ized pointer to a callback handle

Returns:: None
None

get_handle(self)

Gets a pointer to the handle.

Returns:: A SWIG`ized pointer to the handle object

get_pbsz(self)

Return the size of the protection buffer size information

Returns:: the size of the buffer during protected transfers

Raises:: FtpControlException - A FtpControlException is raised if the pbsz cannot be retrieved

get_total_data_channels(self, stripe_ndx)

Returns the number of data channels used so far on this particular stripe

Parameters:: stripe_ndx - The stripe that you wish to query

Returns:: number of channels on that stripe

Raises:: FtpControlException - A FtpControlException if the number of channels could not be determined

local_dcau(self, dcau, credential)

Channel authentication. Update the ftp handle with the given data channel authentication information

Parameters:: dcau - a Python DCAU; credential - a Python GSSCred object

Returns:: None

Raises:: FtpControlException - A FtpControlException is raised if the local_dcau cannot be set

local_mode(self, mode)

Update the ftp handle with the given mode information

Parameters:: mode - a FtpControl Mode type

Returns:: None

Raises:: FtpControlException - A FtpControlException is raised if the local_mode cannot be set

local_parallelism(self, parallelism)

Set the parallelism information in a FTP control handle

Parameters:: parallelism - a ftpControl.Parallelism object

Returns:: None

Raises:: FtpControlException - A FtpControlException is raised if the parallelism could not be set

local_pasv(self)

Create a local listening socket, bind it and return the address the socket is listening to. If there is a existing data connection it is closed.

Returns:: A HostPort object is returned

Raises:: FtpControlException - A FtpControlException is raised if the listening socket cannot be created

local_pbsz(self, size)

Update the ftp handle with the given protection buffer size information

Parameters:: size - the size that the buffer will be during a protected transfer

Returns:: None

Raises:: FtpControlException - A FtpControlException is raised if the local_pbsz cannot be set

local_port(self, address)

Insert the host/port information returned by a PASV on the remote host into the local FTP control handle. (close any outstanding data con)

Parameters:: address - A ftpControl.HostPort object

Returns:: None

Raises:: FtpControlException - A FtpControlException is raised if the host/port information cannot be put into ftp_control handle

local_send_eof(self, eof)

Determines if the library will automatically send an EOF message in extended block mode, or if the user will have to explicity do it by calling data_send_eof

Parameters:: eof - boolean whether to set the handle to have a local eof

Returns:: None

Raises:: FtpControlException - A FtpControlException if the local_eof could not be set

local_spas(self, address_array)

Striped Passive -- enables parallelism and striping

Create num_addresses local listening sockets, bind them and return the addresses the sockets are listening to

Parameters:: address_array - a Python object that wraps an array of host_port_t objects

Returns:: the address_array object

Raises:: FtpControlException -
A FtpControlException is raised if the local_spas cannot be set
As of the globus 2.0 final release this function is not implemented, so an unimplemented exception will always be thrown MKR

local_spor(self, address_array)

Striped Port -- enables parallelism and striping Insert the host/port addresses returned by a SPOR on the remote host into the local FTP control handle.

Parameters:: address_array - a Python object that wraps an array of host_port_t objects

Returns:: the address_array object

Raises:: FtpControlException -
A FtpControlException is raised if the local_spor cannot be set
As of the globus 2.0 final release this function calls the globus_ftp_control_local_spor function which is not implemented, so; unimplemented - A unimplemented exception will always be thrown MKR 6/17/02

local_stru(self, structure)

Update the handle information on the structure of the data being sent on the data channel

Returns:: Nothing.

Raises:: FtpControlException - A FtpControlException if the handle information was not sent.

local_tcp_buffer(self, tcp_buffer)

Update the ftp handle with the given socket buffer size information

Parameters:: tcp_buffer - a ftpControl.TcpBuffer Object

Returns:: None

Raises:: FtpControlException -
A FtpControlException is raised if the local_tcp_buffer cannot be set
The TcpBuffer.set_fixed call must be made on the tcp_buffer object before this call is made

local_type(self, dataType)

Update the FTP control handle with the given type information.

Parameters:: dataType - - A Python string with a single character either 'A' or 'I', for either ascii or image data, which are the only supported types

Returns:: None

Raises:: FtpControlException - A FtpControlException is raised if the local_type cannot be set

operation(self, command)

Retrieves the operation associated with a globus ftp control command.

Parameters:: command - The globus command to be assessed.

Returns:: The operation (buffer) associated with the ftp control command.

quit(self, callback, arg)

send a QUIT to the FTP server and register a response handler

Parameters:: callback - A Python function that has the signature func(user_arg,handle, error, ftp_response); arg - The user_arg to the callback function

Returns:: Returns a SWIG'ized callback handle

Raises:: FtpControlException - A FtpControlException if the QUIT message could not be sent

raw_command(self, command)

Retrieves a raw command from a globus ftp control command.

Parameters:: command - The globus command to be assessed.

Returns:: The raw command (string) corresponding with the command..
None.

read_commands(self, callback, arg)

Begin reading GSIFTP commands. When a command is read the callback function is called with its respective arguments.

Parameters:: callback - The user callback that will be called when commands are read.; arg - The user argument passed to the callback.

Returns:: Returns a SWIG'ized callback handle.

Raises:: FtpControlException - A FtpControlException is raised if the handle argument is NULL, if the handle is not connected or another operation is in progress.

release_data_info(self, write_info)

Releases the memory associated with the write_info object Must be called after each create_data_info call

Parameters:: write_info - a SWIG'ized pointer to a write_info object

Returns:: Nothing

Raises:: FtpControlException - A FtpControlException if the memory to the write_info object cannot be released

send_command(self, cmdspec, callback, arg)

send a command to the FTP server and register a response handler

Parameters:: cmdspec - a string which has the command to be sent to the FTP Server; callback - a Python function that has the signature func(user_arg,handle, error, ftp_response); arg - the user_arg to the callback function

Returns:: Returns a SWIG'ized callback handle

Raises:: FtpControlException - A FtpControlException if the command could not be sent

send_response(self, resp, callback, arg)

Send a response to the GSIFTP client. This function sends a GSIFTP formatted response to the client. When a command callback is received the user calls this function to respond to the user's request.

Parameters:: resp - A formatted string representing the user's response.; callback - The user callback that will be called whtn the response has been sent.; arg - The user argument passed to the callback.

Returns:: Returns a SWIG'ized callback handle.

Raises:: FtpControlException - A FtpControlException if response could not be sent.

x_data_write_stripe(self, buffer, offset, eof, stripe_ndx, write_info)