ft.h File Reference

File Transfer API

gaim. More...

#include "account.h"

Include dependency graph for ft.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  GaimXferUiOps
 File transfer UI operations. More...
struct  _GaimXfer
 A core representation of a file transfer. More...

File Transfer API

GaimXfergaim_xfer_new (GaimAccount *account, GaimXferType type, const char *who)
 Creates a new file transfer handle.
void gaim_xfer_ref (GaimXfer *xfer)
 Increases the reference count on a GaimXfer.
void gaim_xfer_unref (GaimXfer *xfer)
 Decreases the reference count on a GaimXfer.
void gaim_xfer_request (GaimXfer *xfer)
 Requests confirmation for a file transfer from the user.
void gaim_xfer_request_accepted (GaimXfer *xfer, const char *filename)
 Called if the user accepts the file transfer request.
void gaim_xfer_request_denied (GaimXfer *xfer)
 Called if the user rejects the file transfer request.
GaimXferType gaim_xfer_get_type (const GaimXfer *xfer)
 Returns the type of file transfer.
GaimAccount * gaim_xfer_get_account (const GaimXfer *xfer)
 Returns the account the file transfer is using.
GaimXferStatusType gaim_xfer_get_status (const GaimXfer *xfer)
 Returns the status of the xfer.
gboolean gaim_xfer_is_canceled (const GaimXfer *xfer)
 Returns true if the file transfer was canceled.
gboolean gaim_xfer_is_completed (const GaimXfer *xfer)
 Returns the completed state for a file transfer.
const char * gaim_xfer_get_filename (const GaimXfer *xfer)
 Returns the name of the file being sent or received.
const char * gaim_xfer_get_local_filename (const GaimXfer *xfer)
 Returns the file's destination filename,.
size_t gaim_xfer_get_bytes_sent (const GaimXfer *xfer)
 Returns the number of bytes sent so far.
size_t gaim_xfer_get_bytes_remaining (const GaimXfer *xfer)
 Returns the number of bytes received so far.
size_t gaim_xfer_get_size (const GaimXfer *xfer)
 Returns the size of the file being sent or received.
double gaim_xfer_get_progress (const GaimXfer *xfer)
 Returns the current percentage of progress of the transfer.
unsigned int gaim_xfer_get_local_port (const GaimXfer *xfer)
 Returns the local port number in the file transfer.
const char * gaim_xfer_get_remote_ip (const GaimXfer *xfer)
 Returns the remote IP address in the file transfer.
unsigned int gaim_xfer_get_remote_port (const GaimXfer *xfer)
 Returns the remote port number in the file transfer.
void gaim_xfer_set_completed (GaimXfer *xfer, gboolean completed)
 Sets the completed state for the file transfer.
void gaim_xfer_set_message (GaimXfer *xfer, const char *message)
 Sets the filename for the file transfer.
void gaim_xfer_set_filename (GaimXfer *xfer, const char *filename)
 Sets the filename for the file transfer.
void gaim_xfer_set_local_filename (GaimXfer *xfer, const char *filename)
 Sets the local filename for the file transfer.
void gaim_xfer_set_size (GaimXfer *xfer, size_t size)
 Sets the size of the file in a file transfer.
GaimXferUiOpsgaim_xfer_get_ui_ops (const GaimXfer *xfer)
 Returns the UI operations structure for a file transfer.
void gaim_xfer_set_read_fnc (GaimXfer *xfer, ssize_t(*fnc)(char **, GaimXfer *))
 Sets the read function for the file transfer.
void gaim_xfer_set_write_fnc (GaimXfer *xfer, ssize_t(*fnc)(const char *, size_t, GaimXfer *))
 Sets the write function for the file transfer.
void gaim_xfer_set_ack_fnc (GaimXfer *xfer, void(*fnc)(GaimXfer *, const char *, size_t))
 Sets the acknowledge function for the file transfer.
void gaim_xfer_set_request_denied_fnc (GaimXfer *xfer, void(*fnc)(GaimXfer *))
 Sets the function to be called if the request is denied.
void gaim_xfer_set_init_fnc (GaimXfer *xfer, void(*fnc)(GaimXfer *))
 Sets the transfer initialization function for the file transfer.
void gaim_xfer_set_start_fnc (GaimXfer *xfer, void(*fnc)(GaimXfer *))
 Sets the start transfer function for the file transfer.
void gaim_xfer_set_end_fnc (GaimXfer *xfer, void(*fnc)(GaimXfer *))
 Sets the end transfer function for the file transfer.
void gaim_xfer_set_cancel_send_fnc (GaimXfer *xfer, void(*fnc)(GaimXfer *))
 Sets the cancel send function for the file transfer.
void gaim_xfer_set_cancel_recv_fnc (GaimXfer *xfer, void(*fnc)(GaimXfer *))
 Sets the cancel receive function for the file transfer.
ssize_t gaim_xfer_read (GaimXfer *xfer, char **buffer)
 Reads in data from a file transfer stream.
ssize_t gaim_xfer_write (GaimXfer *xfer, const char *buffer, size_t size)
 Writes data to a file transfer stream.
void gaim_xfer_start (GaimXfer *xfer, int fd, const char *ip, unsigned int port)
 Starts a file transfer.
void gaim_xfer_end (GaimXfer *xfer)
 Ends a file transfer.
void gaim_xfer_add (GaimXfer *xfer)
 Adds a new file transfer to the list of file transfers.
void gaim_xfer_cancel_local (GaimXfer *xfer)
 Cancels a file transfer on the local end.
void gaim_xfer_cancel_remote (GaimXfer *xfer)
 Cancels a file transfer from the remote end.
void gaim_xfer_error (GaimXferType type, const char *who, const char *msg)
 Displays a file transfer-related error message.
void gaim_xfer_update_progress (GaimXfer *xfer)
 Updates file transfer progress.
void gaim_xfer_conversation_write (GaimXfer *xfer, char *message, gboolean is_error)
 Displays a file transfer-related message in the conversation window.

UI Registration Functions

void gaim_xfers_set_ui_ops (GaimXferUiOps *ops)
 Sets the UI operations structure to be used in all gaim file transfers.
GaimXferUiOpsgaim_xfers_get_ui_ops (void)
 Returns the UI operations structure to be used in all gaim file transfers.

Typedefs

typedef _GaimXfer GaimXfer
 Data Structures.

Enumerations

enum  GaimXferType { GAIM_XFER_UNKNOWN = 0, GAIM_XFER_SEND, GAIM_XFER_RECEIVE }
 Types of file transfers. More...
enum  GaimXferStatusType {
  GAIM_XFER_STATUS_UNKNOWN = 0, GAIM_XFER_STATUS_NOT_STARTED, GAIM_XFER_STATUS_ACCEPTED, GAIM_XFER_STATUS_STARTED,
  GAIM_XFER_STATUS_DONE, GAIM_XFER_STATUS_CANCEL_LOCAL, GAIM_XFER_STATUS_CANCEL_REMOTE
}
 The different states of the xfer. More...


Detailed Description

File Transfer API

gaim.

Gaim is the legal property of its developers, whose names are too numerous to list here. Please refer to the COPYRIGHT file distributed with this source distribution.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


Enumeration Type Documentation

enum GaimXferStatusType

The different states of the xfer.

Enumerator:
GAIM_XFER_STATUS_UNKNOWN  Unknown, the xfer may be null.
GAIM_XFER_STATUS_NOT_STARTED  It hasn't started yet.
GAIM_XFER_STATUS_ACCEPTED  Receive accepted, but destination file not selected yet.
GAIM_XFER_STATUS_STARTED  gaim_xfer_start has been called.
GAIM_XFER_STATUS_DONE  The xfer completed successfully.
GAIM_XFER_STATUS_CANCEL_LOCAL  The xfer was canceled by us.
GAIM_XFER_STATUS_CANCEL_REMOTE  The xfer was canceled by the other end, or we couldn't connect.

enum GaimXferType

Types of file transfers.

Enumerator:
GAIM_XFER_UNKNOWN  Unknown file transfer type.
GAIM_XFER_SEND  File sending.
GAIM_XFER_RECEIVE  File receiving.


Function Documentation

void gaim_xfer_add ( GaimXfer xfer  ) 

Adds a new file transfer to the list of file transfers.

Call this only if you are not using gaim_xfer_start.

Parameters:
xfer The file transfer.

void gaim_xfer_cancel_local ( GaimXfer xfer  ) 

Cancels a file transfer on the local end.

Parameters:
xfer The file transfer.

void gaim_xfer_cancel_remote ( GaimXfer xfer  ) 

Cancels a file transfer from the remote end.

Parameters:
xfer The file transfer.

void gaim_xfer_conversation_write ( GaimXfer xfer,
char *  message,
gboolean  is_error 
)

Displays a file transfer-related message in the conversation window.

This is a wrapper around gaim_conversation_write

Parameters:
xfer The file transfer to which this message relates.
message The message to display.
gboolean Is this an error message?.

void gaim_xfer_end ( GaimXfer xfer  ) 

Ends a file transfer.

Parameters:
xfer The file transfer.

void gaim_xfer_error ( GaimXferType  type,
const char *  who,
const char *  msg 
)

Displays a file transfer-related error message.

This is a wrapper around gaim_notify_error(), which automatically specifies a title ("File transfer to <i>user</i> aborted" or "File Transfer from <i>user</i> aborted").

Parameters:
type The type of file transfer.
who The user on the other end of the transfer.
msg The message to display.

GaimAccount* gaim_xfer_get_account ( const GaimXfer xfer  ) 

Returns the account the file transfer is using.

Parameters:
xfer The file transfer.
Returns:
The account.

size_t gaim_xfer_get_bytes_remaining ( const GaimXfer xfer  ) 

Returns the number of bytes received so far.

Parameters:
xfer The file transfer.
Returns:
The number of bytes received.

size_t gaim_xfer_get_bytes_sent ( const GaimXfer xfer  ) 

Returns the number of bytes sent so far.

Parameters:
xfer The file transfer.
Returns:
The number of bytes sent.

const char* gaim_xfer_get_filename ( const GaimXfer xfer  ) 

Returns the name of the file being sent or received.

Parameters:
xfer The file transfer.
Returns:
The filename.

const char* gaim_xfer_get_local_filename ( const GaimXfer xfer  ) 

Returns the file's destination filename,.

Parameters:
xfer The file transfer.
Returns:
The destination filename.

unsigned int gaim_xfer_get_local_port ( const GaimXfer xfer  ) 

Returns the local port number in the file transfer.

Parameters:
xfer The file transfer.
Returns:
The port number on this end.

double gaim_xfer_get_progress ( const GaimXfer xfer  ) 

Returns the current percentage of progress of the transfer.

This is a number between 0 (0%) and 1 (100%).

Parameters:
xfer The file transfer.
Returns:
The percentage complete.

const char* gaim_xfer_get_remote_ip ( const GaimXfer xfer  ) 

Returns the remote IP address in the file transfer.

Parameters:
xfer The file transfer.
Returns:
The IP address on the other end.

unsigned int gaim_xfer_get_remote_port ( const GaimXfer xfer  ) 

Returns the remote port number in the file transfer.

Parameters:
xfer The file transfer.
Returns:
The port number on the other end.

size_t gaim_xfer_get_size ( const GaimXfer xfer  ) 

Returns the size of the file being sent or received.

Parameters:
xfer The file transfer.
Returns:
The total size of the file.

GaimXferStatusType gaim_xfer_get_status ( const GaimXfer xfer  ) 

Returns the status of the xfer.

Parameters:
xfer The file transfer.
Returns:
The status.

GaimXferType gaim_xfer_get_type ( const GaimXfer xfer  ) 

Returns the type of file transfer.

Parameters:
xfer The file transfer.
Returns:
The type of the file transfer.

GaimXferUiOps* gaim_xfer_get_ui_ops ( const GaimXfer xfer  ) 

Returns the UI operations structure for a file transfer.

Parameters:
xfer The file transfer.
Returns:
The UI operations structure.

gboolean gaim_xfer_is_canceled ( const GaimXfer xfer  ) 

Returns true if the file transfer was canceled.

Parameters:
xfer The file transfer.
Returns:
Whether or not the transfer was canceled.

gboolean gaim_xfer_is_completed ( const GaimXfer xfer  ) 

Returns the completed state for a file transfer.

Parameters:
xfer The file transfer.
Returns:
The completed state.

GaimXfer* gaim_xfer_new ( GaimAccount *  account,
GaimXferType  type,
const char *  who 
)

Creates a new file transfer handle.

This is called by prpls. The handle starts with a ref count of 1, and this reference is owned by the core. The prpl normally does not need to gaim_xfer_ref or unref.

Parameters:
account The account sending or receiving the file.
type The type of file transfer.
who The name of the remote user.
Returns:
A file transfer handle.

ssize_t gaim_xfer_read ( GaimXfer xfer,
char **  buffer 
)

Reads in data from a file transfer stream.

Parameters:
xfer The file transfer.
buffer The buffer that will be created to contain the data.
Returns:
The number of bytes read, or -1.

void gaim_xfer_ref ( GaimXfer xfer  ) 

Increases the reference count on a GaimXfer.

Please call gaim_xfer_unref later.

Parameters:
xfer A file transfer handle.

void gaim_xfer_request ( GaimXfer xfer  ) 

Requests confirmation for a file transfer from the user.

If receiving a file which is known at this point, this requests user to accept and save the file. If the filename is unknown (not set) this only requests user to accept the file transfer. In this case protocol must call this function again once the filename is available.

Parameters:
xfer The file transfer to request confirmation on.

void gaim_xfer_request_accepted ( GaimXfer xfer,
const char *  filename 
)

Called if the user accepts the file transfer request.

Parameters:
xfer The file transfer.
filename The filename.

void gaim_xfer_request_denied ( GaimXfer xfer  ) 

Called if the user rejects the file transfer request.

Parameters:
xfer The file transfer.

void gaim_xfer_set_ack_fnc ( GaimXfer xfer,
void(*)(GaimXfer *, const char *, size_t)  fnc 
)

Sets the acknowledge function for the file transfer.

Parameters:
xfer The file transfer.
fnc The acknowledge function.

void gaim_xfer_set_cancel_recv_fnc ( GaimXfer xfer,
void(*)(GaimXfer *)  fnc 
)

Sets the cancel receive function for the file transfer.

Parameters:
xfer The file transfer.
fnc The cancel receive function.

void gaim_xfer_set_cancel_send_fnc ( GaimXfer xfer,
void(*)(GaimXfer *)  fnc 
)

Sets the cancel send function for the file transfer.

Parameters:
xfer The file transfer.
fnc The cancel send function.

void gaim_xfer_set_completed ( GaimXfer xfer,
gboolean  completed 
)

Sets the completed state for the file transfer.

Parameters:
xfer The file transfer.
completed The completed state.

void gaim_xfer_set_end_fnc ( GaimXfer xfer,
void(*)(GaimXfer *)  fnc 
)

Sets the end transfer function for the file transfer.

Parameters:
xfer The file transfer.
fnc The end transfer function.

void gaim_xfer_set_filename ( GaimXfer xfer,
const char *  filename 
)

Sets the filename for the file transfer.

Parameters:
xfer The file transfer.
filename The filename.

void gaim_xfer_set_init_fnc ( GaimXfer xfer,
void(*)(GaimXfer *)  fnc 
)

Sets the transfer initialization function for the file transfer.

This function is required, and must call gaim_xfer_start() with the necessary parameters. This will be called if the file transfer is accepted by the user.

Parameters:
xfer The file transfer.
fnc The transfer initialization function.

void gaim_xfer_set_local_filename ( GaimXfer xfer,
const char *  filename 
)

Sets the local filename for the file transfer.

Parameters:
xfer The file transfer.
filename The filename

void gaim_xfer_set_message ( GaimXfer xfer,
const char *  message 
)

Sets the filename for the file transfer.

Parameters:
xfer The file transfer.
message The message.

void gaim_xfer_set_read_fnc ( GaimXfer xfer,
ssize_t(*)(char **, GaimXfer *)  fnc 
)

Sets the read function for the file transfer.

Parameters:
xfer The file transfer.
fnc The read function.

void gaim_xfer_set_request_denied_fnc ( GaimXfer xfer,
void(*)(GaimXfer *)  fnc 
)

Sets the function to be called if the request is denied.

Parameters:
xfer The file transfer.
fnc The request denied prpl callback.

void gaim_xfer_set_size ( GaimXfer xfer,
size_t  size 
)

Sets the size of the file in a file transfer.

Parameters:
xfer The file transfer.
size The size of the file.

void gaim_xfer_set_start_fnc ( GaimXfer xfer,
void(*)(GaimXfer *)  fnc 
)

Sets the start transfer function for the file transfer.

Parameters:
xfer The file transfer.
fnc The start transfer function.

void gaim_xfer_set_write_fnc ( GaimXfer xfer,
ssize_t(*)(const char *, size_t, GaimXfer *)  fnc 
)

Sets the write function for the file transfer.

Parameters:
xfer The file transfer.
fnc The write function.

void gaim_xfer_start ( GaimXfer xfer,
int  fd,
const char *  ip,
unsigned int  port 
)

Starts a file transfer.

Either fd must be specified or ip and port on a file receive transfer. On send, fd must be specified, and ip and port are ignored.

Parameters:
xfer The file transfer.
fd The file descriptor for the socket.
ip The IP address to connect to.
port The port to connect to.

void gaim_xfer_unref ( GaimXfer xfer  ) 

Decreases the reference count on a GaimXfer.

If the reference reaches 0, gaim_xfer_destroy (an internal function) will destroy the xfer. It calls the ui destroy cb first. Since the core keeps a ref on the xfer, only an erroneous call to this function will destroy the xfer while still in use.

Parameters:
xfer A file transfer handle.

void gaim_xfer_update_progress ( GaimXfer xfer  ) 

Updates file transfer progress.

Parameters:
xfer The file transfer.

ssize_t gaim_xfer_write ( GaimXfer xfer,
const char *  buffer,
size_t  size 
)

Writes data to a file transfer stream.

Parameters:
xfer The file transfer.
buffer The buffer to read the data from.
size The number of bytes to write.
Returns:
The number of bytes written, or -1.

GaimXferUiOps* gaim_xfers_get_ui_ops ( void   ) 

Returns the UI operations structure to be used in all gaim file transfers.

Returns:
The UI operations structure.

void gaim_xfers_set_ui_ops ( GaimXferUiOps ops  ) 

Sets the UI operations structure to be used in all gaim file transfers.

Parameters:
ops The UI operations structure.


Generated on Wed Aug 9 23:40:32 2006 for gaim by  doxygen 1.4.7