File transfer

File transfer — client-side wrappers for the File Transfer channel type

Synopsis

#include <telepathy-glib/telepathy-glib-dbus.h>

TpProxyPendingCall * tp_cli_channel_type_file_transfer_call_accept_file
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Address_Type,
                                                         guint in_Access_Control,
                                                         const GValue *in_Access_Control_Param,
                                                         guint64 in_Offset,
                                                         tp_cli_channel_type_file_transfer_callback_for_accept_file callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
TpProxyPendingCall * tp_cli_channel_type_file_transfer_call_provide_file
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Address_Type,
                                                         guint in_Access_Control,
                                                         const GValue *in_Access_Control_Param,
                                                         tp_cli_channel_type_file_transfer_callback_for_provide_file callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_file_transfer_callback_for_accept_file)
                                                        (TpChannel *proxy,
                                                         const GValue *out_Address,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_file_transfer_callback_for_provide_file)
                                                        (TpChannel *proxy,
                                                         const GValue *out_Address,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);
TpProxySignalConnection * tp_cli_channel_type_file_transfer_connect_to_file_transfer_state_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_file_transfer_signal_callback_file_transfer_state_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
TpProxySignalConnection * tp_cli_channel_type_file_transfer_connect_to_initial_offset_defined
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_file_transfer_signal_callback_initial_offset_defined callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
TpProxySignalConnection * tp_cli_channel_type_file_transfer_connect_to_transferred_bytes_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_file_transfer_signal_callback_transferred_bytes_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
TpProxySignalConnection * tp_cli_channel_type_file_transfer_connect_to_uri_defined
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_file_transfer_signal_callback_uri_defined callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);
gboolean            tp_cli_channel_type_file_transfer_run_accept_file
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Address_Type,
                                                         guint in_Access_Control,
                                                         const GValue *in_Access_Control_Param,
                                                         guint64 in_Offset,
                                                         GValue **out_Address,
                                                         GError **error,
                                                         GMainLoop **loop);
gboolean            tp_cli_channel_type_file_transfer_run_provide_file
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Address_Type,
                                                         guint in_Access_Control,
                                                         const GValue *in_Access_Control_Param,
                                                         GValue **out_Address,
                                                         GError **error,
                                                         GMainLoop **loop);
void                (*tp_cli_channel_type_file_transfer_signal_callback_file_transfer_state_changed)
                                                        (TpChannel *proxy,
                                                         guint arg_State,
                                                         guint arg_Reason,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_file_transfer_signal_callback_initial_offset_defined)
                                                        (TpChannel *proxy,
                                                         guint64 arg_InitialOffset,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_file_transfer_signal_callback_transferred_bytes_changed)
                                                        (TpChannel *proxy,
                                                         guint64 arg_Count,
                                                         gpointer user_data,
                                                         GObject *weak_object);
void                (*tp_cli_channel_type_file_transfer_signal_callback_uri_defined)
                                                        (TpChannel *proxy,
                                                         const gchar *arg_URI,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Description

This section documents the auto-generated C wrappers for the File Transfer channel type.

Details

tp_cli_channel_type_file_transfer_call_accept_file ()

TpProxyPendingCall * tp_cli_channel_type_file_transfer_call_accept_file
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Address_Type,
                                                         guint in_Access_Control,
                                                         const GValue *in_Access_Control_Param,
                                                         guint64 in_Offset,
                                                         tp_cli_channel_type_file_transfer_callback_for_accept_file callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a AcceptFile method call.

Accept a file transfer that's in the Pending state. The file transfer's state becomes Accepted after this method is called. At this point the client can connect to the socket. CM MUST emit <tp:member-ref>InitialOffsetDefined</tp:member-ref> and change the state to Open before writing to the socket. Then <tp:member-ref>InitialOffset</tp:member-ref> should be respected in case its value differs from the offset that was specified as an argument to AcceptFile.

proxy :

 the TpProxy

timeout_ms :

 the timeout in milliseconds, or -1 to use the default

in_Address_Type :

 Used to pass an 'in' argument: The type of address the connection manager should listen on. (TpSocketAddressType)

in_Access_Control :

 Used to pass an 'in' argument: The type of access control the connection manager should apply to the socket. (TpSocketAccessControl)

in_Access_Control_Param :

 Used to pass an 'in' argument: A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

in_Offset :

 Used to pass an 'in' argument: The desired offset in bytes where the file transfer should start. The offset is taken from the beginning of the file. Specifying an offset of zero will start the transfer from the beginning of the file. The offset that is actually given in the <tp:member-ref>InitialOffset</tp:member-ref> property can differ from this argument where the requested offset is not supported. (For example, some protocols do not support offsets at all so the InitialOffset property will always be 0.)

callback :

 called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

 user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

 called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

 If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

 a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_type_file_transfer_call_provide_file ()

TpProxyPendingCall * tp_cli_channel_type_file_transfer_call_provide_file
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Address_Type,
                                                         guint in_Access_Control,
                                                         const GValue *in_Access_Control_Param,
                                                         tp_cli_channel_type_file_transfer_callback_for_provide_file callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object);

Start a ProvideFile method call.

Provide the file for an outgoing file transfer which has been offered. Opens a socket that the client can use to provide a file to the connection manager. The channel MUST have been requested, and will change state to Open when this method is called if its state was Accepted.

proxy :

 the TpProxy

timeout_ms :

 the timeout in milliseconds, or -1 to use the default

in_Address_Type :

 Used to pass an 'in' argument: The type of address the connection manager should listen on. (TpSocketAddressType)

in_Access_Control :

 Used to pass an 'in' argument: The type of access control the connection manager should apply to the socket. (TpSocketAccessControl)

in_Access_Control_Param :

 Used to pass an 'in' argument: A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

callback :

 called when the method call succeeds or fails; may be NULL to make a "fire and forget" call with no reply tracking

user_data :

 user-supplied data passed to the callback; must be NULL if callback is NULL

destroy :

 called with the user_data as argument, after the call has succeeded, failed or been cancelled; must be NULL if callback is NULL

weak_object :

 If not NULL, a GObject which will be weakly referenced; if it is destroyed, this call will automatically be cancelled. Must be NULL if callback is NULL

Returns :

 a TpProxyPendingCall representing the call in progress. It is borrowed from the object, and will become invalid when the callback is called, the call is cancelled or the TpProxy becomes invalid.

tp_cli_channel_type_file_transfer_callback_for_accept_file ()

void                (*tp_cli_channel_type_file_transfer_callback_for_accept_file)
                                                        (TpChannel *proxy,
                                                         const GValue *out_Address,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a AcceptFile method call succeeds or fails.

proxy :

 the proxy on which the call was made

out_Address :

 Used to return an 'out' argument if error is NULL: The address on which the connection manager will listen for connections for this file transfer.

error :

 NULL on success, or an error on failure

user_data :

 user-supplied data

weak_object :

 user-supplied object

tp_cli_channel_type_file_transfer_callback_for_provide_file ()

void                (*tp_cli_channel_type_file_transfer_callback_for_provide_file)
                                                        (TpChannel *proxy,
                                                         const GValue *out_Address,
                                                         const GError *error,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Signature of the callback called when a ProvideFile method call succeeds or fails.

proxy :

 the proxy on which the call was made

out_Address :

 Used to return an 'out' argument if error is NULL: The address on which the connection manager will listen for connections for this file transfer.

error :

 NULL on success, or an error on failure

user_data :

 user-supplied data

weak_object :

 user-supplied object

tp_cli_channel_type_file_transfer_connect_to_file_transfer_state_changed ()

TpProxySignalConnection * tp_cli_channel_type_file_transfer_connect_to_file_transfer_state_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_file_transfer_signal_callback_file_transfer_state_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal FileTransferStateChanged.

Emitted when the state of a file transfer changes.

proxy :

 A TpChannel or subclass

callback :

 Callback to be called when the signal is received

user_data :

 User-supplied data for the callback

destroy :

 Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

 A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

 If not NULL, used to raise an error if NULL is returned

Returns :

 a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_channel_type_file_transfer_connect_to_initial_offset_defined ()

TpProxySignalConnection * tp_cli_channel_type_file_transfer_connect_to_initial_offset_defined
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_file_transfer_signal_callback_initial_offset_defined callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal InitialOffsetDefined.

Emitted when the value of the <tp:member-ref>InitialOffset</tp:member-ref> property has been negotiated. This signal MUST be emitted before the channel becomes Open and clients have to use this offset when transferring the file.

proxy :

 A TpChannel or subclass

callback :

 Callback to be called when the signal is received

user_data :

 User-supplied data for the callback

destroy :

 Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

 A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

 If not NULL, used to raise an error if NULL is returned

Returns :

 a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_channel_type_file_transfer_connect_to_transferred_bytes_changed ()

TpProxySignalConnection * tp_cli_channel_type_file_transfer_connect_to_transferred_bytes_changed
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_file_transfer_signal_callback_transferred_bytes_changed callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal TransferredBytesChanged.

Emitted when the number of transferred bytes changes. This will not be signalled with every single byte change. Instead, the most frequent this signal will be emitted is once a second. This should be sufficient, and the <tp:member-ref>TransferredBytes</tp:member-ref> property SHOULD NOT be polled.

proxy :

 A TpChannel or subclass

callback :

 Callback to be called when the signal is received

user_data :

 User-supplied data for the callback

destroy :

 Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

 A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

 If not NULL, used to raise an error if NULL is returned

Returns :

 a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_channel_type_file_transfer_connect_to_uri_defined ()

TpProxySignalConnection * tp_cli_channel_type_file_transfer_connect_to_uri_defined
                                                        (TpChannel *proxy,
                                                         tp_cli_channel_type_file_transfer_signal_callback_uri_defined callback,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy,
                                                         GObject *weak_object,
                                                         GError **error);

Connect a handler to the signal URIDefined.

Emitted when the value of the <tp:member-ref>URI</tp:member-ref> property has been set. This signal MUST only be emitted on incoming file transfers, and only if the handler sets the <tp:member-ref>URI</tp:member-ref> property before accepting the file.

proxy :

 A TpChannel or subclass

callback :

 Callback to be called when the signal is received

user_data :

 User-supplied data for the callback

destroy :

 Destructor for the user-supplied data, which will be called when this signal is disconnected, or before this function returns NULL

weak_object :

 A GObject which will be weakly referenced; if it is destroyed, this callback will automatically be disconnected

error :

 If not NULL, used to raise an error if NULL is returned

Returns :

 a TpProxySignalConnection containing all of the above, which can be used to disconnect the signal; or NULL if the proxy does not have the desired interface or has become invalid.

tp_cli_channel_type_file_transfer_run_accept_file ()

gboolean            tp_cli_channel_type_file_transfer_run_accept_file
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Address_Type,
                                                         guint in_Access_Control,
                                                         const GValue *in_Access_Control_Param,
                                                         guint64 in_Offset,
                                                         GValue **out_Address,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_channel_type_file_transfer_run_accept_file is deprecated and should not be used in newly-written code.

Call the method AcceptFile and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Accept a file transfer that's in the Pending state. The file transfer's state becomes Accepted after this method is called. At this point the client can connect to the socket. CM MUST emit <tp:member-ref>InitialOffsetDefined</tp:member-ref> and change the state to Open before writing to the socket. Then <tp:member-ref>InitialOffset</tp:member-ref> should be respected in case its value differs from the offset that was specified as an argument to AcceptFile.

proxy :

 A TpChannel or subclass

timeout_ms :

 Timeout in milliseconds, or -1 for default

in_Address_Type :

 Used to pass an 'in' argument: The type of address the connection manager should listen on. (TpSocketAddressType)

in_Access_Control :

 Used to pass an 'in' argument: The type of access control the connection manager should apply to the socket. (TpSocketAccessControl)

in_Access_Control_Param :

 Used to pass an 'in' argument: A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

in_Offset :

 Used to pass an 'in' argument: The desired offset in bytes where the file transfer should start. The offset is taken from the beginning of the file. Specifying an offset of zero will start the transfer from the beginning of the file. The offset that is actually given in the <tp:member-ref>InitialOffset</tp:member-ref> property can differ from this argument where the requested offset is not supported. (For example, some protocols do not support offsets at all so the InitialOffset property will always be 0.)

out_Address :

 Used to return an 'out' argument if TRUE is returned: The address on which the connection manager will listen for connections for this file transfer.

error :

 If not NULL, used to return errors if FALSE is returned

loop :

 If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

 TRUE on success, FALSE and sets error on error

tp_cli_channel_type_file_transfer_run_provide_file ()

gboolean            tp_cli_channel_type_file_transfer_run_provide_file
                                                        (TpChannel *proxy,
                                                         gint timeout_ms,
                                                         guint in_Address_Type,
                                                         guint in_Access_Control,
                                                         const GValue *in_Access_Control_Param,
                                                         GValue **out_Address,
                                                         GError **error,
                                                         GMainLoop **loop);

Warning

tp_cli_channel_type_file_transfer_run_provide_file is deprecated and should not be used in newly-written code.

Call the method ProvideFile and run the main loop until it returns. Before calling this method, you must add a reference to any borrowed objects you need to keep, and generally ensure that everything is in a consistent state.

Provide the file for an outgoing file transfer which has been offered. Opens a socket that the client can use to provide a file to the connection manager. The channel MUST have been requested, and will change state to Open when this method is called if its state was Accepted.

proxy :

 A TpChannel or subclass

timeout_ms :

 Timeout in milliseconds, or -1 for default

in_Address_Type :

 Used to pass an 'in' argument: The type of address the connection manager should listen on. (TpSocketAddressType)

in_Access_Control :

 Used to pass an 'in' argument: The type of access control the connection manager should apply to the socket. (TpSocketAccessControl)

in_Access_Control_Param :

 Used to pass an 'in' argument: A parameter for the access control type, to be interpreted as specified in the documentation for the Socket_Access_Control enum.

out_Address :

 Used to return an 'out' argument if TRUE is returned: The address on which the connection manager will listen for connections for this file transfer.

error :

 If not NULL, used to return errors if FALSE is returned

loop :

 If not NULL, set before re-entering the main loop, to point to a GMainLoop which can be used to cancel this call with g_main_loop_quit(), causing a return of FALSE with error set to TP_DBUS_ERROR_CANCELLED

Returns :

 TRUE on success, FALSE and sets error on error

tp_cli_channel_type_file_transfer_signal_callback_file_transfer_state_changed ()

void                (*tp_cli_channel_type_file_transfer_signal_callback_file_transfer_state_changed)
                                                        (TpChannel *proxy,
                                                         guint arg_State,
                                                         guint arg_Reason,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal FileTransferStateChanged.

proxy :

 The proxy on which tp_cli_channel_type_file_transfer_connect_to_file_transfer_state_changed() was called

arg_State :

 The new state of the file transfer; see the File_Transfer_State enumeration. (TpFileTransferState)

arg_Reason :

 The reason for the state change; see the File_Transfer_State_Change_Reason enumeration. The value will always be File_Transfer_State_Change_Reason_None, except when changing state to cancelled. (TpFileTransferStateChangeReason)

user_data :

 User-supplied data

weak_object :

 User-supplied weakly referenced object

tp_cli_channel_type_file_transfer_signal_callback_initial_offset_defined ()

void                (*tp_cli_channel_type_file_transfer_signal_callback_initial_offset_defined)
                                                        (TpChannel *proxy,
                                                         guint64 arg_InitialOffset,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal InitialOffsetDefined.

proxy :

 The proxy on which tp_cli_channel_type_file_transfer_connect_to_initial_offset_defined() was called

arg_InitialOffset :

 The value of the <tp:member-ref>InitialOffset</tp:member-ref> property.

user_data :

 User-supplied data

weak_object :

 User-supplied weakly referenced object

tp_cli_channel_type_file_transfer_signal_callback_transferred_bytes_changed ()

void                (*tp_cli_channel_type_file_transfer_signal_callback_transferred_bytes_changed)
                                                        (TpChannel *proxy,
                                                         guint64 arg_Count,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal TransferredBytesChanged.

proxy :

 The proxy on which tp_cli_channel_type_file_transfer_connect_to_transferred_bytes_changed() was called

arg_Count :

 The number of already transferred bytes.

user_data :

 User-supplied data

weak_object :

 User-supplied weakly referenced object

tp_cli_channel_type_file_transfer_signal_callback_uri_defined ()

void                (*tp_cli_channel_type_file_transfer_signal_callback_uri_defined)
                                                        (TpChannel *proxy,
                                                         const gchar *arg_URI,
                                                         gpointer user_data,
                                                         GObject *weak_object);

Represents the signature of a callback for the signal URIDefined.

proxy :

 The proxy on which tp_cli_channel_type_file_transfer_connect_to_uri_defined() was called

arg_URI :

 The value of the <tp:member-ref>URI</tp:member-ref> property.

user_data :

 User-supplied data

weak_object :

 User-supplied weakly referenced object

See Also

TpChannel
Generated by GTK-Doc V1.19