Media command classes

The QPlayer API exposes a set of command classes for specifying parameters of media operations and for reading operation results.

When issuing requests to browse media or to read metadata, information on tracks, or playback state information, clients must pass in a pointer to a command object containing the request parameters. The API defines a command class for each operation type. For example, to browse the contents of a folder on a media source, a client must create a BrowseCommand object, specify in that object the IDs of the media source and folder that it wants to browse, and then pass in a pointer to that object when calling QPlayer::browse().

For all operations, clients must create a command object that specifies the operation parameters, wait for it to emit a complete signal (which indicates the operation succeeded), and then read the operation results by calling the object's result() method.

Note: You must wait for the complete signal before retrieving the results; otherwise, the results will be empty. The library calls a command object's setResult() method to write the results data in the object, but this method is meant for internal use only.

If a command fails, the object instead emits an error signal. Your client code can call the errorMessage() function to get information about the error.

Command objects include pointers to themselves in their emitted complete and error signals. These objects delete themselves after the callbacks that process these signals finish executing. So, the client doesn't have to do any memory management for these objects.

Source code sample

The following code sample searches a media source. It's adapted from the reference HMI SearchModel implementation.

// Create a pointer to a SearchCommand instance, 
// specifying the media source ID and search term parameters
QPlayer::SearchCommand *command = 
        new QPlayer::SearchCommand( 1, QStringLiteral("time") );

// Connect a slot to the command's 'complete' signal. 
// This slot is called when the command completes successfully.
connect( command, &QPlayer::SearchCommand::complete, this, 
         &SearchModel::Private::onSearchResult );

// Connect a slot to the command's 'error' signal. 
// This slot is called when the command fails.
connect( command, &QPlayer::SearchCommand::error, this, 
         &SearchModel::Private::onSearchError );

// Start the search by passing the SearchCommand pointer to the
// search() method
q->m_qPlayer->search(command);

The complete handler looks like this:

void SearchModel::Private::onSearchResult(
                        QPlayer::SearchCommand *command )
{
    // The result of a search command is a list of type 
    // QList<QPlayer::MediaNode>. Check if we received a single
    // search result node; if so, output its ID.
    if( command->result().length() == 1 ) {
        qDebug() << command->result().at(0).id;
    }

    // We don't need to clean up the memory allocated for the 
    // command because it deletes itself after the 'complete' and
    // 'error' signal handlers finish executing. 
    // For this reason, it's important not to keep copies of the 
    // command pointer after the signal handlers are called. 
    // If the command results are needed outside the handlers,
    // the results should be copied.
}