## RBTransferTarget

RBTransferTarget — interface for sources that can receive track transfers

## Synopsis

    #include <rb-transfer-target.h>

    struct              RBTransferTargetInterface;
    char *              rb_transfer_target_build_dest_uri   (RBTransferTarget *target,
                                                             RhythmDBEntry *entry,
                                                             const char *media_type,
                                                             const char *extension);
    void                rb_transfer_target_track_added      (RBTransferTarget *target,
                                                             RhythmDBEntry *entry,
                                                             const char *uri,
                                                             guint64 filesize,
                                                             const char *media_type);
    void                rb_transfer_target_track_add_error  (RBTransferTarget *target,
                                                             RhythmDBEntry *entry,
                                                             const char *uri,
                                                             GError *error);
    gboolean            rb_transfer_target_should_transfer  (RBTransferTarget *target,
                                                             RhythmDBEntry *entry);
    GList *             rb_transfer_target_get_format_descriptions
                                                            (RBTransferTarget *target);
    gboolean            rb_transfer_target_check_category   (RBTransferTarget *target,
                                                             RhythmDBEntry *entry);
    gboolean            rb_transfer_target_check_duplicate  (RBTransferTarget *target,
                                                             RhythmDBEntry *entry);
    RBTrackTransferBatch * rb_transfer_target_transfer      (RBTransferTarget *target,
                                                             GList *entries,
                                                             gboolean defer);

## Description

Sources that can accept track transfers should implement this interface and call the associated functions to perform transfers. The source needs to be able to construct target URIs for transfers, and can optionally perform its own processing after transfers have finished. The source must also provide a GstEncodingTarget that describes the formats it accepts.

## Details

### struct RBTransferTargetInterface

    struct RBTransferTargetInterface {
    	GTypeInterface g_iface;

    	char*		(*build_dest_uri) (RBTransferTarget *target,
    						 RhythmDBEntry *entry,
    						 const char *media_type,
    						 const char *extension);
    	gboolean (*track_added)		(RBTransferTarget *target,
    						 RhythmDBEntry *entry,
    						 const char *uri,
    						 guint64 dest_size,
    						 const char *media_type);
    	gboolean (*track_add_error) (RBTransferTarget *target,
    						 RhythmDBEntry *entry,
    						 const char *uri,
    						 GError *error);
    	gboolean (*should_transfer) (RBTransferTarget *target,
    						 RhythmDBEntry *entry);
    };

### rb_transfer_target_build_dest_uri ()

    char *              rb_transfer_target_build_dest_uri   (RBTransferTarget *target,
                                                             RhythmDBEntry *entry,
                                                             const char *media_type,
                                                             const char *extension);

Constructs a URI to use as the destination for a transfer or transcoding operation. The URI may be on the device itself, if the device is mounted into the normal filesystem or through gvfs, or it may be a temporary location used to store the file before uploading it to the device.

The destination URI should conform to the device's normal URI format, and should use the provided extension instead of the extension from the source entry.

`target` : | an RBTransferTarget
`entry` : | a RhythmDBEntry being transferred
`media_type` : | destination media type
`extension` : | extension associated with destination media type
Returns : | constructed URI

### rb_transfer_target_track_added ()

    void                rb_transfer_target_track_added      (RBTransferTarget *target,
                                                             RhythmDBEntry *entry,
                                                             const char *uri,
                                                             guint64 filesize,
                                                             const char *media_type);

This is called when a transfer to the target has completed. If the source's `track_added` method returns `TRUE`, the destination URI will be added to the database using the entry type for the device.

If the target uses a temporary area as the destination for transfers, it can instead upload the destination file to the device and create an entry for it, then return `FALSE`.

`target` : | an RBTransferTarget
`entry` : | the source RhythmDBEntry for the transfer
`uri` : | the destination URI
`filesize` : | size of the destination file
`media_type` : | media type of the destination file

### rb_transfer_target_track_add_error ()

    void                rb_transfer_target_track_add_error  (RBTransferTarget *target,
                                                             RhythmDBEntry *entry,
                                                             const char *uri,
                                                             GError *error);

This is called when a transfer fails. If the source's impl_track_add_error implementation returns `TRUE`, an error dialog will be displayed to the user containing the error message, unless the error indicates that the destination file already exists.

`target` : | an RBTransferTarget
`entry` : | the source RhythmDBEntry for the transfer
`uri` : | the destination URI
`error` : | the transfer error information

### rb_transfer_target_should_transfer ()

    gboolean            rb_transfer_target_should_transfer  (RBTransferTarget *target,
                                                             RhythmDBEntry *entry);

Checks whether `entry` should be transferred to the target. The target can check whether a matching entry already exists on the device, for instance. `rb_transfer_target_check_duplicate` may form part of an implementation. If this method returns `FALSE`, the entry will be skipped.

`target` : | an RBTransferTarget
`entry` : | a RhythmDBEntry to consider transferring
Returns : | `TRUE` if the entry should be transferred to the target

### rb_transfer_target_get_format_descriptions ()

    GList *             rb_transfer_target_get_format_descriptions
                                                            (RBTransferTarget *target);

Returns a GList of allocated media format descriptions for the formats supported by the target. The list and the strings it holds must be freed by the caller.

`target` : | an RBTransferTarget
Returns : | list of descriptions. [element-type utf8][transfer full]

### rb_transfer_target_check_category ()

    gboolean            rb_transfer_target_check_category   (RBTransferTarget *target,
                                                             RhythmDBEntry *entry);

This checks that the entry type of `entry` is in a suitable category for transfer. This can be used to implement `should_transfer`.

`target` : | an RBTransferTarget
`entry` : | a RhythmDBEntry to check
Returns : | `TRUE` if the entry is in a suitable category

### rb_transfer_target_check_duplicate ()

    gboolean            rb_transfer_target_check_duplicate  (RBTransferTarget *target,
                                                             RhythmDBEntry *entry);

This checks for an existing entry in the target that matches the title, album, artist, and track number of the entry being considered. This can be used to implement `should_transfer`.

`target` : | an RBTransferTarget
`entry` : | a RhythmDBEntry to check
Returns : | `TRUE` if the entry already exists on the target.

### rb_transfer_target_transfer ()

    RBTrackTransferBatch * rb_transfer_target_transfer      (RBTransferTarget *target,
                                                             GList *entries,
                                                             gboolean defer);

Starts tranferring `entries` to the target. This returns the RBTrackTransferBatch that it starts, so the caller can track the progress of the transfer, or NULL if the target doesn't want any of the entries.

`target` : | an RBTransferTarget
`entries` : | a GList of entries to transfer. [element-type RB.RhythmDBEntry]
`defer` : | if `TRUE`, don't start the transfer until
Returns : | an RBTrackTransferBatch, or NULL. [transfer full]