pidgin 2.14.14dev
|
File Transfer API. More...
Go to the source code of this file.
Data Structures | |
struct | PurpleXferUiOps |
File transfer UI operations. More... | |
struct | _PurpleXfer |
A core representation of a file transfer. More... | |
Typedefs | |
typedef struct _PurpleXfer | PurpleXfer |
Data Structures | |
Enumerations | |
enum | PurpleXferType { PURPLE_XFER_UNKNOWN = 0 , PURPLE_XFER_SEND , PURPLE_XFER_RECEIVE } |
Types of file transfers. More... | |
enum | PurpleXferStatusType { PURPLE_XFER_STATUS_UNKNOWN = 0 , PURPLE_XFER_STATUS_NOT_STARTED , PURPLE_XFER_STATUS_ACCEPTED , PURPLE_XFER_STATUS_STARTED , PURPLE_XFER_STATUS_DONE , PURPLE_XFER_STATUS_CANCEL_LOCAL , PURPLE_XFER_STATUS_CANCEL_REMOTE } |
The different states of the xfer. More... | |
Functions | |
File Transfer API <br> | |
PurpleXfer * | purple_xfer_new (PurpleAccount *account, PurpleXferType type, const char *who) |
Creates a new file transfer handle. | |
GList * | purple_xfers_get_all (void) |
Returns all xfers. | |
void | purple_xfer_ref (PurpleXfer *xfer) |
Increases the reference count on a PurpleXfer. | |
void | purple_xfer_unref (PurpleXfer *xfer) |
Decreases the reference count on a PurpleXfer. | |
void | purple_xfer_request (PurpleXfer *xfer) |
Requests confirmation for a file transfer from the user. | |
void | purple_xfer_request_accepted (PurpleXfer *xfer, const char *filename) |
Called if the user accepts the file transfer request. | |
void | purple_xfer_request_denied (PurpleXfer *xfer) |
Called if the user rejects the file transfer request. | |
PurpleXferType | purple_xfer_get_type (const PurpleXfer *xfer) |
Returns the type of file transfer. | |
PurpleAccount * | purple_xfer_get_account (const PurpleXfer *xfer) |
Returns the account the file transfer is using. | |
const char * | purple_xfer_get_remote_user (const PurpleXfer *xfer) |
Returns the name of the remote user. | |
PurpleXferStatusType | purple_xfer_get_status (const PurpleXfer *xfer) |
Returns the status of the xfer. | |
gboolean | purple_xfer_is_canceled (const PurpleXfer *xfer) |
Returns true if the file transfer was cancelled. | |
gboolean | purple_xfer_is_completed (const PurpleXfer *xfer) |
Returns the completed state for a file transfer. | |
const char * | purple_xfer_get_filename (const PurpleXfer *xfer) |
Returns the name of the file being sent or received. | |
const char * | purple_xfer_get_local_filename (const PurpleXfer *xfer) |
Returns the file's destination filename,. | |
size_t | purple_xfer_get_bytes_sent (const PurpleXfer *xfer) |
Returns the number of bytes sent (or received) so far. | |
size_t | purple_xfer_get_bytes_remaining (const PurpleXfer *xfer) |
Returns the number of bytes remaining to send or receive. | |
size_t | purple_xfer_get_size (const PurpleXfer *xfer) |
Returns the size of the file being sent or received. | |
double | purple_xfer_get_progress (const PurpleXfer *xfer) |
Returns the current percentage of progress of the transfer. | |
unsigned int | purple_xfer_get_local_port (const PurpleXfer *xfer) |
Returns the local port number in the file transfer. | |
const char * | purple_xfer_get_remote_ip (const PurpleXfer *xfer) |
Returns the remote IP address in the file transfer. | |
unsigned int | purple_xfer_get_remote_port (const PurpleXfer *xfer) |
Returns the remote port number in the file transfer. | |
time_t | purple_xfer_get_start_time (const PurpleXfer *xfer) |
Returns the time the transfer of a file started. | |
time_t | purple_xfer_get_end_time (const PurpleXfer *xfer) |
Returns the time the transfer of a file ended. | |
void | purple_xfer_set_completed (PurpleXfer *xfer, gboolean completed) |
Sets the completed state for the file transfer. | |
void | purple_xfer_set_message (PurpleXfer *xfer, const char *message) |
Sets the filename for the file transfer. | |
void | purple_xfer_set_filename (PurpleXfer *xfer, const char *filename) |
Sets the filename for the file transfer. | |
void | purple_xfer_set_local_filename (PurpleXfer *xfer, const char *filename) |
Sets the local filename for the file transfer. | |
void | purple_xfer_set_size (PurpleXfer *xfer, size_t size) |
Sets the size of the file in a file transfer. | |
void | purple_xfer_set_bytes_sent (PurpleXfer *xfer, size_t bytes_sent) |
Sets the current working position in the active file transfer. | |
PurpleXferUiOps * | purple_xfer_get_ui_ops (const PurpleXfer *xfer) |
Returns the UI operations structure for a file transfer. | |
void | purple_xfer_set_read_fnc (PurpleXfer *xfer, gssize(*fnc)(guchar **, PurpleXfer *)) |
Sets the read function for the file transfer. | |
void | purple_xfer_set_write_fnc (PurpleXfer *xfer, gssize(*fnc)(const guchar *, size_t, PurpleXfer *)) |
Sets the write function for the file transfer. | |
void | purple_xfer_set_ack_fnc (PurpleXfer *xfer, void(*fnc)(PurpleXfer *, const guchar *, size_t)) |
Sets the acknowledge function for the file transfer. | |
void | purple_xfer_set_request_denied_fnc (PurpleXfer *xfer, void(*fnc)(PurpleXfer *)) |
Sets the function to be called if the request is denied. | |
void | purple_xfer_set_init_fnc (PurpleXfer *xfer, void(*fnc)(PurpleXfer *)) |
Sets the transfer initialization function for the file transfer. | |
void | purple_xfer_set_start_fnc (PurpleXfer *xfer, void(*fnc)(PurpleXfer *)) |
Sets the start transfer function for the file transfer. | |
void | purple_xfer_set_end_fnc (PurpleXfer *xfer, void(*fnc)(PurpleXfer *)) |
Sets the end transfer function for the file transfer. | |
void | purple_xfer_set_cancel_send_fnc (PurpleXfer *xfer, void(*fnc)(PurpleXfer *)) |
Sets the cancel send function for the file transfer. | |
void | purple_xfer_set_cancel_recv_fnc (PurpleXfer *xfer, void(*fnc)(PurpleXfer *)) |
Sets the cancel receive function for the file transfer. | |
gssize | purple_xfer_read (PurpleXfer *xfer, guchar **buffer) |
Reads in data from a file transfer stream. | |
gssize | purple_xfer_write (PurpleXfer *xfer, const guchar *buffer, gsize size) |
Writes data to a file transfer stream. | |
gboolean | purple_xfer_write_file (PurpleXfer *xfer, const guchar *buffer, gsize size) |
Writes chunk of received file. | |
gssize | purple_xfer_read_file (PurpleXfer *xfer, guchar *buffer, gsize size) |
Writes chunk of file being sent. | |
void | purple_xfer_start (PurpleXfer *xfer, int fd, const char *ip, unsigned int port) |
Starts a file transfer. | |
void | purple_xfer_end (PurpleXfer *xfer) |
Ends a file transfer. | |
void | purple_xfer_add (PurpleXfer *xfer) |
Adds a new file transfer to the list of file transfers. | |
void | purple_xfer_cancel_local (PurpleXfer *xfer) |
Cancels a file transfer on the local end. | |
void | purple_xfer_cancel_remote (PurpleXfer *xfer) |
Cancels a file transfer from the remote end. | |
void | purple_xfer_error (PurpleXferType type, PurpleAccount *account, const char *who, const char *msg) |
Displays a file transfer-related error message. | |
void | purple_xfer_update_progress (PurpleXfer *xfer) |
Updates file transfer progress. | |
void | purple_xfer_conversation_write (PurpleXfer *xfer, char *message, gboolean is_error) |
Displays a file transfer-related message in the conversation window. | |
void | purple_xfer_ui_ready (PurpleXfer *xfer) |
Allows the UI to signal it's ready to send/receive data (depending on the direction of the file transfer. | |
void | purple_xfer_prpl_ready (PurpleXfer *xfer) |
Allows the prpl to signal it's ready to send/receive data (depending on the direction of the file transfer. | |
gconstpointer | purple_xfer_get_thumbnail (const PurpleXfer *xfer, gsize *len) |
Gets the thumbnail data for a transfer. | |
const gchar * | purple_xfer_get_thumbnail_mimetype (const PurpleXfer *xfer) |
Gets the mimetype of the thumbnail preview for a transfer. | |
void | purple_xfer_set_thumbnail (PurpleXfer *xfer, gconstpointer thumbnail, gsize size, const gchar *mimetype) |
Sets the thumbnail data for a transfer. | |
void | purple_xfer_prepare_thumbnail (PurpleXfer *xfer, const gchar *formats) |
Prepare a thumbnail for a transfer (if the UI supports it) will be no-op in case the UI doesn't implement thumbnail creation. | |
UI Registration Functions <br> | |
void * | purple_xfers_get_handle (void) |
Returns the handle to the file transfer subsystem. | |
void | purple_xfers_init (void) |
Initializes the file transfer subsystem. | |
void | purple_xfers_uninit (void) |
Uninitializes the file transfer subsystem. | |
void | purple_xfers_set_ui_ops (PurpleXferUiOps *ops) |
Sets the UI operations structure to be used in all purple file transfers. | |
PurpleXferUiOps * | purple_xfers_get_ui_ops (void) |
Returns the UI operations structure to be used in all purple file transfers. | |
typedef struct _PurpleXfer PurpleXfer |
enum PurpleXferStatusType |
The different states of the xfer.
enum PurpleXferType |
void purple_xfer_add | ( | PurpleXfer * | xfer | ) |
Adds a new file transfer to the list of file transfers.
Call this only if you are not using purple_xfer_start.
xfer | The file transfer. |
void purple_xfer_cancel_local | ( | PurpleXfer * | xfer | ) |
Cancels a file transfer on the local end.
xfer | The file transfer. |
void purple_xfer_cancel_remote | ( | PurpleXfer * | xfer | ) |
Cancels a file transfer from the remote end.
xfer | The file transfer. |
void purple_xfer_conversation_write | ( | PurpleXfer * | xfer, |
char * | message, | ||
gboolean | is_error | ||
) |
Displays a file transfer-related message in the conversation window.
This is a wrapper around purple_conversation_write
xfer | The file transfer to which this message relates. |
message | The message to display. |
is_error | Is this an error message?. |
void purple_xfer_end | ( | PurpleXfer * | xfer | ) |
Ends a file transfer.
xfer | The file transfer. |
void purple_xfer_error | ( | PurpleXferType | type, |
PurpleAccount * | account, | ||
const char * | who, | ||
const char * | msg | ||
) |
Displays a file transfer-related error message.
This is a wrapper around purple_notify_error(), which automatically specifies a title ("File transfer to <i>user</i> failed" or "File Transfer from <i>user</i> failed").
type | The type of file transfer. |
account | The account sending or receiving the file. |
who | The user on the other end of the transfer. |
msg | The message to display. |
PurpleAccount * purple_xfer_get_account | ( | const PurpleXfer * | xfer | ) |
Returns the account the file transfer is using.
xfer | The file transfer. |
size_t purple_xfer_get_bytes_remaining | ( | const PurpleXfer * | xfer | ) |
Returns the number of bytes remaining to send or receive.
xfer | The file transfer. |
size_t purple_xfer_get_bytes_sent | ( | const PurpleXfer * | xfer | ) |
Returns the number of bytes sent (or received) so far.
xfer | The file transfer. |
time_t purple_xfer_get_end_time | ( | const PurpleXfer * | xfer | ) |
Returns the time the transfer of a file ended.
xfer | The file transfer. |
const char * purple_xfer_get_filename | ( | const PurpleXfer * | xfer | ) |
Returns the name of the file being sent or received.
xfer | The file transfer. |
const char * purple_xfer_get_local_filename | ( | const PurpleXfer * | xfer | ) |
Returns the file's destination filename,.
xfer | The file transfer. |
unsigned int purple_xfer_get_local_port | ( | const PurpleXfer * | xfer | ) |
Returns the local port number in the file transfer.
xfer | The file transfer. |
double purple_xfer_get_progress | ( | const PurpleXfer * | xfer | ) |
Returns the current percentage of progress of the transfer.
This is a number between 0 (0%) and 1 (100%).
xfer | The file transfer. |
const char * purple_xfer_get_remote_ip | ( | const PurpleXfer * | xfer | ) |
Returns the remote IP address in the file transfer.
xfer | The file transfer. |
unsigned int purple_xfer_get_remote_port | ( | const PurpleXfer * | xfer | ) |
Returns the remote port number in the file transfer.
xfer | The file transfer. |
const char * purple_xfer_get_remote_user | ( | const PurpleXfer * | xfer | ) |
Returns the name of the remote user.
xfer | The file transfer. |
size_t purple_xfer_get_size | ( | const PurpleXfer * | xfer | ) |
Returns the size of the file being sent or received.
xfer | The file transfer. |
time_t purple_xfer_get_start_time | ( | const PurpleXfer * | xfer | ) |
Returns the time the transfer of a file started.
xfer | The file transfer. |
PurpleXferStatusType purple_xfer_get_status | ( | const PurpleXfer * | xfer | ) |
Returns the status of the xfer.
xfer | The file transfer. |
gconstpointer purple_xfer_get_thumbnail | ( | const PurpleXfer * | xfer, |
gsize * | len | ||
) |
Gets the thumbnail data for a transfer.
xfer | The file transfer to get the thumbnail for |
len | If not NULL , the length of the thumbnail data returned will be set in the location pointed to by this. |
const gchar * purple_xfer_get_thumbnail_mimetype | ( | const PurpleXfer * | xfer | ) |
Gets the mimetype of the thumbnail preview for a transfer.
xfer | The file transfer to get the mimetype for |
NULL
if not thumbnail is set PurpleXferType purple_xfer_get_type | ( | const PurpleXfer * | xfer | ) |
Returns the type of file transfer.
xfer | The file transfer. |
PurpleXferUiOps * purple_xfer_get_ui_ops | ( | const PurpleXfer * | xfer | ) |
Returns the UI operations structure for a file transfer.
xfer | The file transfer. |
gboolean purple_xfer_is_canceled | ( | const PurpleXfer * | xfer | ) |
Returns true if the file transfer was cancelled.
xfer | The file transfer. |
gboolean purple_xfer_is_completed | ( | const PurpleXfer * | xfer | ) |
Returns the completed state for a file transfer.
xfer | The file transfer. |
PurpleXfer * purple_xfer_new | ( | PurpleAccount * | account, |
PurpleXferType | 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 purple_xfer_ref or unref.
account | The account sending or receiving the file. |
type | The type of file transfer. |
who | The name of the remote user. |
void purple_xfer_prepare_thumbnail | ( | PurpleXfer * | xfer, |
const gchar * | formats | ||
) |
Prepare a thumbnail for a transfer (if the UI supports it) will be no-op in case the UI doesn't implement thumbnail creation.
xfer | The file transfer to create a thumbnail for |
formats | A comma-separated list of mimetypes for image formats the protocols can use for thumbnails. |
void purple_xfer_prpl_ready | ( | PurpleXfer * | xfer | ) |
Allows the prpl to signal it's ready to send/receive data (depending on the direction of the file transfer.
Used when the prpl provides read/write ops and cannot/does not provide a raw fd to the core.
xfer | The file transfer which is ready. |
gssize purple_xfer_read | ( | PurpleXfer * | xfer, |
guchar ** | buffer | ||
) |
Reads in data from a file transfer stream.
xfer | The file transfer. |
buffer | The buffer that will be created to contain the data. |
gssize purple_xfer_read_file | ( | PurpleXfer * | xfer, |
guchar * | buffer, | ||
gsize | size | ||
) |
Writes chunk of file being sent.
xfer | The file transfer. |
buffer | The buffer to write the data to. |
size | The size of buffer. |
void purple_xfer_ref | ( | PurpleXfer * | xfer | ) |
Increases the reference count on a PurpleXfer.
Please call purple_xfer_unref later.
xfer | A file transfer handle. |
void purple_xfer_request | ( | PurpleXfer * | 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.
xfer | The file transfer to request confirmation on. |
void purple_xfer_request_accepted | ( | PurpleXfer * | xfer, |
const char * | filename | ||
) |
Called if the user accepts the file transfer request.
xfer | The file transfer. |
filename | The filename. |
void purple_xfer_request_denied | ( | PurpleXfer * | xfer | ) |
Called if the user rejects the file transfer request.
xfer | The file transfer. |
void purple_xfer_set_ack_fnc | ( | PurpleXfer * | xfer, |
void(*)(PurpleXfer *, const guchar *, size_t) | fnc | ||
) |
Sets the acknowledge function for the file transfer.
xfer | The file transfer. |
fnc | The acknowledge function. |
void purple_xfer_set_bytes_sent | ( | PurpleXfer * | xfer, |
size_t | bytes_sent | ||
) |
Sets the current working position in the active file transfer.
This can be used to jump backward in the file if the protocol detects that some bit of data needs to be resent or has been sent twice.
It's used for pausing and resuming an oscar file transfer.
xfer | The file transfer. |
bytes_sent | The new current position in the file. If we're sending a file then this is the byte that we will send. If we're receiving a file, this is the next byte that we expect to receive. |
void purple_xfer_set_cancel_recv_fnc | ( | PurpleXfer * | xfer, |
void(*)(PurpleXfer *) | fnc | ||
) |
Sets the cancel receive function for the file transfer.
xfer | The file transfer. |
fnc | The cancel receive function. |
void purple_xfer_set_cancel_send_fnc | ( | PurpleXfer * | xfer, |
void(*)(PurpleXfer *) | fnc | ||
) |
Sets the cancel send function for the file transfer.
xfer | The file transfer. |
fnc | The cancel send function. |
void purple_xfer_set_completed | ( | PurpleXfer * | xfer, |
gboolean | completed | ||
) |
Sets the completed state for the file transfer.
xfer | The file transfer. |
completed | The completed state. |
void purple_xfer_set_end_fnc | ( | PurpleXfer * | xfer, |
void(*)(PurpleXfer *) | fnc | ||
) |
Sets the end transfer function for the file transfer.
xfer | The file transfer. |
fnc | The end transfer function. |
void purple_xfer_set_filename | ( | PurpleXfer * | xfer, |
const char * | filename | ||
) |
Sets the filename for the file transfer.
xfer | The file transfer. |
filename | The filename. |
void purple_xfer_set_init_fnc | ( | PurpleXfer * | xfer, |
void(*)(PurpleXfer *) | fnc | ||
) |
Sets the transfer initialization function for the file transfer.
This function is required, and must call purple_xfer_start() with the necessary parameters. This will be called if the file transfer is accepted by the user.
xfer | The file transfer. |
fnc | The transfer initialization function. |
void purple_xfer_set_local_filename | ( | PurpleXfer * | xfer, |
const char * | filename | ||
) |
Sets the local filename for the file transfer.
xfer | The file transfer. |
filename | The filename |
void purple_xfer_set_message | ( | PurpleXfer * | xfer, |
const char * | message | ||
) |
Sets the filename for the file transfer.
xfer | The file transfer. |
message | The message. |
void purple_xfer_set_read_fnc | ( | PurpleXfer * | xfer, |
gssize(*)(guchar **, PurpleXfer *) | fnc | ||
) |
Sets the read function for the file transfer.
xfer | The file transfer. |
fnc | The read function. |
void purple_xfer_set_request_denied_fnc | ( | PurpleXfer * | xfer, |
void(*)(PurpleXfer *) | fnc | ||
) |
Sets the function to be called if the request is denied.
xfer | The file transfer. |
fnc | The request denied prpl callback. |
void purple_xfer_set_size | ( | PurpleXfer * | xfer, |
size_t | size | ||
) |
Sets the size of the file in a file transfer.
xfer | The file transfer. |
size | The size of the file. |
void purple_xfer_set_start_fnc | ( | PurpleXfer * | xfer, |
void(*)(PurpleXfer *) | fnc | ||
) |
Sets the start transfer function for the file transfer.
xfer | The file transfer. |
fnc | The start transfer function. |
void purple_xfer_set_thumbnail | ( | PurpleXfer * | xfer, |
gconstpointer | thumbnail, | ||
gsize | size, | ||
const gchar * | mimetype | ||
) |
Sets the thumbnail data for a transfer.
xfer | The file transfer to set the data for |
thumbnail | A pointer to the thumbnail data, this will be copied |
size | The size in bytes of the passed in thumbnail data |
mimetype | The mimetype of the generated thumbnail |
void purple_xfer_set_write_fnc | ( | PurpleXfer * | xfer, |
gssize(*)(const guchar *, size_t, PurpleXfer *) | fnc | ||
) |
Sets the write function for the file transfer.
xfer | The file transfer. |
fnc | The write function. |
void purple_xfer_start | ( | PurpleXfer * | 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.
Prior to libpurple 2.6.0, passing '0' to fd was special-cased to allow the protocol plugin to facilitate the file transfer itself. As of 2.6.0, this is supported (for backward compatibility), but will be removed in libpurple 3.0.0. If a prpl detects that the running libpurple is running 2.6.0 or higher, it should use the invalid fd '-1'.
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 purple_xfer_ui_ready | ( | PurpleXfer * | xfer | ) |
Allows the UI to signal it's ready to send/receive data (depending on the direction of the file transfer.
Used when the UI is providing read/write/data_not_sent UI ops.
xfer | The file transfer which is ready. |
void purple_xfer_unref | ( | PurpleXfer * | xfer | ) |
Decreases the reference count on a PurpleXfer.
If the reference reaches 0, purple_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.
xfer | A file transfer handle. |
void purple_xfer_update_progress | ( | PurpleXfer * | xfer | ) |
Updates file transfer progress.
xfer | The file transfer. |
gssize purple_xfer_write | ( | PurpleXfer * | xfer, |
const guchar * | buffer, | ||
gsize | size | ||
) |
Writes data to a file transfer stream.
xfer | The file transfer. |
buffer | The buffer to read the data from. |
size | The number of bytes to write. |
gboolean purple_xfer_write_file | ( | PurpleXfer * | xfer, |
const guchar * | buffer, | ||
gsize | size | ||
) |
Writes chunk of received file.
xfer | The file transfer. |
buffer | The buffer to read the data from. |
size | The number of bytes to write. |
GList * purple_xfers_get_all | ( | void | ) |
Returns all xfers.
void * purple_xfers_get_handle | ( | void | ) |
Returns the handle to the file transfer subsystem.
PurpleXferUiOps * purple_xfers_get_ui_ops | ( | void | ) |
Returns the UI operations structure to be used in all purple file transfers.
void purple_xfers_set_ui_ops | ( | PurpleXferUiOps * | ops | ) |
Sets the UI operations structure to be used in all purple file transfers.
ops | The UI operations structure. |