RBTrackTransferBatch

RBTrackTransferBatch — batch track transfer job

Synopsis

struct              RBTrackTransferBatch;
struct              RBTrackTransferBatchClass;
RBTrackTransferBatch *	 rb_track_transfer_batch_new     (GList *media_type_list,
                                                         const char * const *media_types,
                                                         GObject *source,
                                                         GObject *destination);
void                rb_track_transfer_batch_add         (RBTrackTransferBatch *batch,
                                                         RhythmDBEntry *entry);
guint               rb_track_transfer_batch_check_media_types
                                                        (RBTrackTransferBatch *batch);
void                rb_track_transfer_batch_cancel      (RBTrackTransferBatch *batch);

Object Hierarchy

  GObject
   +----RBTrackTransferBatch

Properties

  "destination"              RBSource*             : Read / Write / Construct Only
  "done-entries"             gint                  : Read
  "entry-list"               gpointer              : Read
  "media-types"              gpointer              : Write / Construct Only
  "media-types-strv"         GStrv                 : Read / Write / Construct Only
  "progress"                 gdouble               : Read
  "source"                   RBSource*             : Read / Write / Construct Only
  "total-entries"            gint                  : Read

Signals

  "cancelled"                                      : Run Last
  "complete"                                       : Run Last
  "get-dest-uri"                                   : Run Last
  "overwrite-prompt"                               : Run Last
  "started"                                        : Run Last
  "track-done"                                     : Run Last
  "track-progress"                                 : Run Last
  "track-started"                                  : Run Last

Description

Manages the transfer of a set of tracks (using RBEncoder), providing overall status information and allowing the transfer to be cancelled as a single unit.

Details

struct RBTrackTransferBatch

struct RBTrackTransferBatch;


struct RBTrackTransferBatchClass

struct RBTrackTransferBatchClass {
	GObjectClass parent_class;

	/* signals */
	void (*started)		(RBTrackTransferBatch *batch);
	void (*cancelled)		(RBTrackTransferBatch *batch);
	void (*complete)		(RBTrackTransferBatch *batch);

	char *  (*get_dest_uri)		(RBTrackTransferBatch *batch,
					 RhythmDBEntry *entry,
					 const char *mediatype,
					 const char *extension);
	gboolean (*overwrite_prompt) (RBTrackTransferBatch *batch,
					 GFile *dest_file);
	void (*track_started) (RBTrackTransferBatch *batch,
					 RhythmDBEntry *entry,
					 const char *dest);
	void (*track_progress) (RBTrackTransferBatch *batch,
					 RhythmDBEntry *entry,
					 const char *dest,
					 int done,
					 int total,
					 double fraction);
	void (*track_done)		(RBTrackTransferBatch *batch,
					 RhythmDBEntry *entry,
					 const char *dest,
					 guint64 dest_size,
					 GError *error);
};


rb_track_transfer_batch_new ()

RBTrackTransferBatch *	 rb_track_transfer_batch_new     (GList *media_type_list,
                                                         const char * const *media_types,
                                                         GObject *source,
                                                         GObject *destination);

Creates a new transfer batch with the specified output types. Only one of media_types and media_types_list may be specified.

One or more entries must be added to the batch (using rb_track_transfer_batch_add) before the batch can be started (rb_track_transfer_manager_start_batch).

media_type_list :

GList containing media type strings.

media_types :

array containing media type strings describing allowable output formats

source :

the RBSource from which the entries are to be transferred

destination :

the RBSource to which the entries are to be transferred

Returns :

new RBTrackTransferBatch object

rb_track_transfer_batch_add ()

void                rb_track_transfer_batch_add         (RBTrackTransferBatch *batch,
                                                         RhythmDBEntry *entry);

Adds an entry to be transferred.

batch :

a RBTrackTransferBatch

entry :

the source RhythmDBEntry to transfer

rb_track_transfer_batch_check_media_types ()

guint               rb_track_transfer_batch_check_media_types
                                                        (RBTrackTransferBatch *batch);

Checks that all entries in the batch can be transferred in a format supported by the destination.

batch :

a RBTrackTransferBatch

Returns :

number of entries that cannot be transferred

rb_track_transfer_batch_cancel ()

void                rb_track_transfer_batch_cancel      (RBTrackTransferBatch *batch);

Cancels the batch.

Property Details

The "destination" property

  "destination"              RBSource*             : Read / Write / Construct Only

The RBSource to which the tracks are being transferred.


The "done-entries" property

  "done-entries"             gint                  : Read

Number of entries in the batch that have been transferred.

Allowed values: >= 0

Default value: 0


The "entry-list" property

  "entry-list"               gpointer              : Read

A list of all entries in the batch.


The "media-types" property

  "media-types"              gpointer              : Write / Construct Only

GList of media type strings describing the acceptable destination formats. If NULL, no format conversion will be done.


The "media-types-strv" property

  "media-types-strv"         GStrv                 : Read / Write / Construct Only

Set of allowable destination media types.


The "progress" property

  "progress"                 gdouble               : Read

Fraction of the transfer batch that has been processed.

Allowed values: [0,1]

Default value: 0


The "source" property

  "source"                   RBSource*             : Read / Write / Construct Only

The RBSource from which the tracks are being transferred.


The "total-entries" property

  "total-entries"            gint                  : Read

Total number of entries in the transfer batch.

Allowed values: >= 0

Default value: 0

Signal Details

The "cancelled" signal

void                user_function                      (RBTrackTransferBatch *batch,
                                                        gpointer              user_data)      : Run Last

Emitted when the batch is cancelled.

hmm. will 'complete' still be emitted in this case?

batch :

the RBTrackTransferBatch

user_data :

user data set when the signal handler was connected.

The "complete" signal

void                user_function                      (RBTrackTransferBatch *batch,
                                                        gpointer              user_data)      : Run Last

Emitted when the batch is complete. This will be immediately after the final entry transfer is complete.

batch :

the RBTrackTransferBatch

user_data :

user data set when the signal handler was connected.

The "get-dest-uri" signal

gchar*              user_function                      (RBTrackTransferBatch *batch,
                                                        RhythmDBEntry        *entry,
                                                        gchar                *mediatype,
                                                        gchar                *extension,
                                                        gpointer              user_data)      : Run Last

The batch emits this to allow the creator to provide a destination URI for an entry being transferred. This is emitted after the output media type is decided, so the usual extension for the media type can be taken into consideration.

batch :

the RBTrackTransferBatch

entry :

the RhythmDBEntry to be transferred

mediatype :

the destination media type for the transfer

extension :

usual extension for the destionation media type

user_data :

user data set when the signal handler was connected.

The "overwrite-prompt" signal

gboolean            user_function                      (RBTrackTransferBatch *batch,
                                                        GFile                *file,
                                                        gpointer              user_data)      : Run Last

Emitted when the destination URI for a transfer already exists. If a handler returns TRUE, the file will be overwritten, otherwise the transfer will be skipped.

batch :

the RBTrackTransferBatch

file :

the GFile that may be overwritten

user_data :

user data set when the signal handler was connected.

The "started" signal

void                user_function                      (RBTrackTransferBatch *batch,
                                                        gpointer              user_data)      : Run Last

Emitted when the batch is started. This will be after all previous batches have finished, which is not necessarily when rb_track_transfer_manager_start_batch is called.

batch :

the RBTrackTransferBatch

user_data :

user data set when the signal handler was connected.

The "track-done" signal

void                user_function                      (RBTrackTransferBatch *batch,
                                                        RhythmDBEntry        *entry,
                                                        gchar                *dest,
                                                        guint64               dest_size,
                                                        gchar                *dest_mediatype,
                                                        gpointer              error,
                                                        gpointer              user_data)           : Run Last

Emitted when a track transfer is complete, whether because the track was fully transferred, because an error occurred, or because the batch was cancelled (maybe..).

batch :

the RBTrackTransferBatch

entry :

the RhythmDBEntry that was transferred

dest :

the destination URI for the transfer

dest_size :

size of the destination file

dest_mediatype :

the media type of the destination file

error :

any error that occurred during transfer

user_data :

user data set when the signal handler was connected.

The "track-progress" signal

void                user_function                      (RBTrackTransferBatch *batch,
                                                        RhythmDBEntry        *entry,
                                                        gchar                *dest,
                                                        gint                  done,
                                                        gint                  total,
                                                        gdouble               fraction,
                                                        gpointer              user_data)      : Run Last

Emitted regularly throughout the transfer to allow progress bars and other UI elements to be updated.

batch :

the RBTrackTransferBatch

entry :

the RhythmDBEntry being transferred

dest :

the destination URI for the transfer

done :

some measure of how much of the transfer is done

total :

the total amount of that same measure

fraction :

the fraction of the transfer that is done

user_data :

user data set when the signal handler was connected.

The "track-started" signal

void                user_function                      (RBTrackTransferBatch *batch,
                                                        RhythmDBEntry        *entry,
                                                        gchar                *dest,
                                                        gpointer              user_data)      : Run Last

Emitted when a new entry is about to be transferred. This will be emitted for each entry in the batch, unless the batch is cancelled.

batch :

the RBTrackTransferBatch

entry :

the RhythmDBEntry being transferred

dest :

the destination URI for the transfer

user_data :

user data set when the signal handler was connected.