NowPlayingConnection

Since: BlackBerry 10.0.0

#include <bb/multimedia/NowPlayingConnection>

To link against this class, add the following line to your .pro file: LIBS += -lbbmultimedia

Provides exclusive system access to media notification areas.

The NowPlayingConnection class provides exclusive system access to the media information area that describe the media that is currently active on the device. This class also provides a means to receive media control event notifications.

A now playing example in C++:

NowPlayingConnection np("myConnection", this);
QVariantMap metadata;

metadata[MetaData::Title] = "Sample Track";
metadata[MetaData::Artist] = "Sample Artist";
metadata[MetaData::Album] = "Sample Album";

np->setMetaData(metadata);

np->setIconUrl(
    QUrl("file://%1/app/native/assets/artwork.png")
    .arg(QDir::currentPath()));

The service must be acquired before playing. A service that is playing will automatically revoke any other connected user.

np->acquire();

Once the acquired() signal is received, it is possible to send the media data:

// Represents 2min duration in milliseconds.
np->setDuration(120000);

// Represents the starting position.
np->setPosition(0);

// Notifies of the playing media state.
np->setMediaState(bb::multimedia::MediaState::Started);

Acquired signals can be used in calls to next(), previous(), play(), pause(), and stop(). Upon receiving a signal, the user must call the function that is most appropriate for their media.

Once a revoked() signal has been received, playback of the media must be stopped and all media resources must be released. For example, an audio recorder that receives a revoked() signal must give up its access to the microphone, which could allow another process to use it.

The controllerActive property provides notification to indicate that one or more controllers are attached to the service that is currently acquired. The controllers require regular status updates to function accurately. This means that even if an application is in standby mode, regular status messages should continue to be sent to it.

With no audioManagerHandle specified, the now playing service will automatically call play() when no longer preempted. If an audioManagerHandle is specified, the now playing service will only call play() if the audio routing has not changed to a more public device while preempted.

A now playing example in QML:

import bb.multimedia 1.0
...
attachedObjects: [
    NowPlayingConnection {
        id: nowplaying

        connectionName: "myConnection"
        iconUrl: "asset:///artwork.png"

        onAcquired: {
          var metadata = { "track": "MyTrack", "artist" : "MyArtist" };

          nowplaying.duration = 120000; // 2min in milliseconds
          nowplaying.position = 0;

          nowplaying.mediaState = MediaState.Started;

          nowplaying.setMetaData(metadata);
        }

        onPause: {
          mymedia.pause();
        }

        onPlay: {
          mymedia.play();
        }

        onRevoked: {
          mymedia.stop();
        }
    }
]
...
onMyMediaWantsToPlay: {
    nowplaying.acquire();
}
...
onMyMediaPaused: {
    nowplaying.mediaState = MediaState.Paused;
}
...
onMyMediaPositionChanged: {
    nowplaying.position = ms;
}
...
onMyMediaNoLongerWantsToPlay: {
    nowplaying.revoke();
}
...
onMyMediaTrackHasChanged: {
    nowplaying.trackChange();
}


Overview

Public Functions Index

NowPlayingConnection (QObject *parent=0)
NowPlayingConnection (const QString &connectionName, QObject *parent=0)
NowPlayingConnection (const QString &connectionName, bb::multimedia::PriorityLevel::Type priorityLevel, QObject *parent=0)
virtual ~NowPlayingConnection ()
unsigned intaudioManagerHandle () const
QStringconnectionName () const
unsigned intduration () const
QUrliconUrl () const
boolisAcquired () const
boolisControllerActive () const
boolisNextEnabled () const
boolisPreemptable () const BB_MULTIMEDIA_DEPRECATED
boolisPreempted () const
boolisPreviousEnabled () const
QStringlastRevokingConnectionName () const
unsigned intlastRevokingConnectionPid () const
bb::multimedia::MediaState::TypemediaState () const
bb::multimedia::OverlayStyle::TypeoverlayStyle () const
unsigned intposition () const
bb::multimedia::PriorityLevel::TypepriorityLevel () const
bb::multimedia::RepeatMode::TyperepeatMode () const
bb::multimedia::MediaError::TypesetAudioManagerHandle (unsigned int audioManagerHandle)
bb::multimedia::ShuffleMode::TypeshuffleMode () const

Public Slots Index

bb::multimedia::MediaError::Typeacquire ()
bb::multimedia::MediaError::Typerevoke ()
voidsetDuration (unsigned int duration)
voidsetIconUrl (const QUrl &url)
voidsetMediaState (bb::multimedia::MediaState::Type state)
voidsetMetaData (const QVariantMap &metadata)
voidsetNextEnabled (bool nextEnabled)
voidsetOverlayStyle (bb::multimedia::OverlayStyle::Type overlayStyle)
voidsetPosition (unsigned int position)
voidsetPreemptable (bool preemptable) BB_MULTIMEDIA_DEPRECATED
voidsetPreviousEnabled (bool previousEnabled)
voidsetRepeatMode (bb::multimedia::RepeatMode::Type repeatMode)
voidsetShuffleMode (bb::multimedia::ShuffleMode::Type shuffleMode)
bb::multimedia::MediaError::TypetrackChange ()

Signals Index

voidacquired ()
voidaudioManagerHandleChanged (unsigned int audioManagerHandle)
voidcontrollerActiveChanged (bool controllerActive)
voiddurationChanged (unsigned int duration)
voidforward ()
voidiconUrlChanged (const QUrl &url)
voidmediaStateChanged (bb::multimedia::MediaState::Type mediaState)
voidmetaDataChanged (const QVariantMap &metadata)
voidnext ()
voidnextEnabledChanged (bool nextEnabled)
voidoverlayStyleChanged (bb::multimedia::OverlayStyle::Type overlayStyle)
voidpause ()
voidplay ()
voidpositionChanged (unsigned int position)
voidpreemptableChanged (bool preemptable) BB_MULTIMEDIA_DEPRECATED
voidprevious ()
voidpreviousEnabledChanged (bool previousEnabled)
voidrepeat ()
voidrepeatModeChanged (bb::multimedia::RepeatMode::Type repeatMode)
voidrevoked ()
voidrewind ()
voidshuffle ()
voidshuffleModeChanged (bb::multimedia::ShuffleMode::Type shuffleMode)
voidstop ()

Properties

bool acquired[read-only]

Represents a flag indicating if the now playing connection has been acquired.

Since:

BlackBerry 10.0.0

QVariant audioManagerHandle

Represents the handle of an externally managed audio manager.

Since:

BlackBerry 10.0.0

QString connectionName[read-only]

Represents the connection name registered with the now playing service.

NOTE: This property can only be set during object construction.

Since:

BlackBerry 10.0.0

bool controllerActive[read-only]

Represents a flag that indicates if one or more controllers are active on an acquired connection.

Active controllers can be internal or external to an application, and require regular status updates.

Since:

BlackBerry 10.0.0

QVariant duration

Represents the duration of the player in milliseconds.

Since:

BlackBerry 10.0.0

QUrl iconUrl

Represents the path to an icon that should be displayed in the notification area.

Since:

BlackBerry 10.0.0

QString lastRevokingConnectionName[read-only]

Represents the connection name of the last now playing connection to revoke this connection.

Since:

BlackBerry 10.0.0

QVariant lastRevokingConnectionPid[read-only]

Represents the process ID of the last now playing connection to revoke this connection.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaState::Type mediaState

Represents the media state of the connection that is currently playing.

Since:

BlackBerry 10.0.0

bool nextEnabled

Represents a flag indicating if the next button should be enabled when using OverlayStyle::Fancy.

Since:

BlackBerry 10.0.0

bb::multimedia::OverlayStyle::Type overlayStyle

Represents the overlay style to use when displaying now playing metadata.

Since:

BlackBerry 10.0.0

QVariant position

Represents the current position of the player in milliseconds.

Since:

BlackBerry 10.0.0

bool preemptable

Deprecated.

Represents a flag indicating the preemptable state of the connection.

Since:

BlackBerry 10.0.0

bool preempted[read-only]

Represents a flag indicating if the connection is preempted or not by a higher priority connection.

Since:

BlackBerry 10.0.0

bool previousEnabled

Represents a flag indicating if the previous button should be enabled when using OverlayStyle::Fancy.

Since:

BlackBerry 10.0.0

bb::multimedia::PriorityLevel::Type priorityLevel[read-only]

Represents priority level of the connection.

The priority level indicates whether the connection can be preempted/acquired/revoked by other connections.

Since:

BlackBerry 10.3.0

bb::multimedia::RepeatMode::Type repeatMode

Represents the current repeat mode for the player.

The repeat mode of the player can be RepeatMode::None, RepeatMode::Track, or RepeatMode::All. The default is RepeatMode::Unsupported.

Since:

BlackBerry 10.3.0

bb::multimedia::ShuffleMode::Type shuffleMode

Represents the current shuffle mode for the player.

The shuffle mode of the player can be ShuffleMode::Off, or ShuffleMode::All. The default is ShuffleMode::Unsupported.

Since:

BlackBerry 10.3.0

Public Functions

NowPlayingConnection (

NowPlayingConnection class constructor.

Parameters
parent

An optional parameter to specify the parent of this QObject.

Since:

BlackBerry 10.0.0

NowPlayingConnection (

NowPlayingConnection class constructor.

Parameters
connectionName

The name to use to identify with the platform now playing service. connection in relation to other connections.

parent

An optional parameter to specify the parent of this QObject.

Since:

BlackBerry 10.0.0

NowPlayingConnection (

NowPlayingConnection class constructor.

Parameters
connectionName

The name to use to identify with the platform now playing service.

priorityLevel

The priority level determining the behavior of the connection in relation to other connections.

parent

An optional parameter to specify the parent of this QObject.

Since:

BlackBerry 10.3.0

virtual~NowPlayingConnection ()

Destructor.

Since:

BlackBerry 10.0.0

unsigned int audioManagerHandle ()

Returns the handle of an externally managed audio manager.

Return:

Returns the handle of an externally managed audio manager or zero if not set.

Since:

BlackBerry 10.0.0

QString connectionName ()

Used to return the name of the now playing connection.

Return:

Returns the name of the now playing connection visible to the now playing service.

Since:

BlackBerry 10.0.0

unsigned int duration ()

Used to determine the track duration.

Return:

Returns a number representing the duration in milliseconds of the track being played.

Since:

BlackBerry 10.0.0

QUrl iconUrl ()

Used to return the icon path.

Return:

Returns the URL path of an icon that will used in the notification area.

Since:

BlackBerry 10.0.0

bool isAcquired ()

Used to determine if a particular NowPlayingConnection instance has successfully acquired the connection.

Return:

Returns true when the connection has been acquired, and false otherwise.

Since:

BlackBerry 10.0.0

bool isControllerActive ()

Determines if one or more controllers are active on the service that is currently acquired.

Active controllers can be internal or external to an application, and require regular status updates.

Return:

Returns true when one or more controllers are active, and false otherwise.

Since:

BlackBerry 10.0.0

bool isNextEnabled ()

A flag to indicate if the Next button is enabled.

Return:

Returns true if the Next button is enabled on overlays using the OverlayStyle::Fancy property, and false otherwise.

Since:

BlackBerry 10.0.0

bool isPreemptable ()

A flag to indicate if an acquired connection is preemptable or not by another now playing connection.

Deprecated.

The method was deprecated because setting this flag in setPreemptable to false would not stop another high level priority connection from acquiring the resources. Therefore this method gives invalid results.

The method was replaced by Priority Level approach. See PriorityLevel property documentation for details.

Return:

Returns true if the connection is preemptable, and false otherwise.

Since:

BlackBerry 10.0.0

bool isPreempted ()

A flag to indicate if the current connection has been preempted by a higher priority connection or not.

If this connection is not acquired, the function will return false.

Return:

Returns true if the connection is currently preempted, and false otherwise.

Since:

BlackBerry 10.0.0

bool isPreviousEnabled ()

A flag to indicate if the Previous button is enabled.

Return:

Returns true if the Previous button is enabled on overlays using the OverlayStyle::Fancy property, and false otherwise.

Since:

BlackBerry 10.0.0

QString lastRevokingConnectionName ()

Used to return the name of the connection that last revoked this now playing connection.

Return:

Returns the name of a now playing connection.

Since:

BlackBerry 10.0.0

unsigned int lastRevokingConnectionPid ()

Used to return the process ID of the connection that last revoked this now playing connection.

Return:

Returns the process ID of a now playing connection. If never revoked, a PID of zero is returned.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaState::Type mediaState ()

Used to determine the now playing connection state.

Return:

Returns the current connection state, which can be stopped, playing, or paused.

Since:

BlackBerry 10.0.0

bb::multimedia::OverlayStyle::Type overlayStyle ()

Used to determine the overlay style to use for displaying now playing metadata.

Return:

Returns the connection overlay style set with setOverlayStyle.

Since:

BlackBerry 10.0.0

unsigned int position ()

Used to determine the track position.

Return:

Returns a number representing the current playback position in milliseconds of the track being played.

Since:

BlackBerry 10.0.0

bb::multimedia::PriorityLevel::Type priorityLevel ()

Returns the connection priority level.

Can be used for defining if any other connection can acquire now playing service from this connection. See PriorityLevel documentation for details.

Since:

BlackBerry 10.3.0

bb::multimedia::RepeatMode::Type repeatMode ()

Retrieves the current player repeat mode as set by a call from setRepeatMode().

Return:

Returns the current player repeat mode.

Since:

BlackBerry 10.3.0

bb::multimedia::MediaError::Type setAudioManagerHandle (
  • unsigned intaudioManagerHandle)

Sets the handle of an externally managed audio manager.

Changing this property will allow the now playing service to perform targeted auto resume functionality using the specified audio manager handle. Setting an audio manager handle of zero will reset to no registered audio manager. The original owner of the audio manager handle is responsible for releasing it.

Parameters
audioManagerHandle

The audio manager handle to use.

Return:

Returns the last recording error.

Since:

BlackBerry 10.0.0

bb::multimedia::ShuffleMode::Type shuffleMode ()

Retrieves the current player shuffle mode as set by a call from setShuffleMode().

Return:

Returns the current player shuffle mode.

Since:

BlackBerry 10.3.0

Public Slots

bb::multimedia::MediaError::Type acquire ()

Used to request exclusive access to the now playing service.

Access will be granted based on priority level of connection A, already acquired, and connection B, trying to acquire nowplaying service. See PriorityLevel documentation for details.

Return:

Returns a media error that occurred calling this function or MediaError::None if the call completed successfully.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaError::Type revoke ()

Used to revoke this connection if acquired.

If this connection is acquired, it will result in the revoked() signal being emitted. If the connection is not acquired, no action will be taken on the object.

Return:

Returns a media error that occurred calling this function or MediaError::None if the call completed successfully.

Since:

BlackBerry 10.0.0

void setDuration (
  • unsigned intduration)

Used to set the number representing the duration (in milliseconds) of the track being played.

Parameters
duration

The duration of the current track.

Since:

BlackBerry 10.0.0

void setIconUrl (

Used to set the URL to an icon that can be displayed in a now playing notification area.

This could be the album artwork or an icon representing the application owning the connection.

Parameters
url

The URL to an image to representing the current now playing track.

Since:

BlackBerry 10.0.0

void setMediaState (

Used to notify the now playing connection of the current playback state.

Parameters
state

The current playback state, which can be playing, stopped, or paused.

Since:

BlackBerry 10.0.0

void setMetaData (

Used to notify the now playing connection of the metadata associated with the current media source.

Parameters
metadata

An object containing the metadata associated with the connection that is currently playing.

Since:

BlackBerry 10.0.0

void setNextEnabled (
  • boolnextEnabled)

Used to set whether or not the Next button should be enabled on overlays.

When enabled, this flag makes the Next button usable while the overlayStyle property is set to OverlayStyle::Fancy. This flag is ignored when the overlayStyle property is set to OverlayStyle::Plain.

Parameters
nextEnabled

If true the Next button should be enabled, if false the Next button should not be enabled.

Since:

BlackBerry 10.0.0

void setOverlayStyle (

Used to set the overlay style to use for currently playing metadata.

The default is OverlayStyle::Plain.

Parameters
overlayStyle

The overlay style to set on the NowPlayingConnection.

Since:

BlackBerry 10.0.0

void setPosition (
  • unsigned intposition)

Used to set a number representing the current playback position (in milliseconds) of the track being played.

Parameters
position

The position of the current track.

Since:

BlackBerry 10.0.0

void setPreemptable (
  • boolpreemptable)

Deprecated.

When disabled, no other connection can acquire the now playing service from this acquired connection. If a preemptable connection is currently acquired, it will be paused until this connection revokes itself.

The method was replaced by Priority Level approach. See PriorityLevel property documentation for details.

Parameters
preemptable

If true an acquired connection is preemptible, if false an acquired connection is not preemptible.

Since:

BlackBerry 10.0.0

void setPreviousEnabled (
  • boolpreviousEnabled)

Used to set whether or not the Previous button should be enabled on overlays.

When enabled, the Previous button will be usable when using OverlayStyle::Fancy. For OverlayStyle::Plain this flag is ignored.

Parameters
previousEnabled

If true the Previous button should be enabled, if false the Previous button should not be enabled.

Since:

BlackBerry 10.0.0

void setRepeatMode (

Used to set the value of the repeat mode for the player.

This function sets the repeat mode for the player. Any active controller will be notified of the current mode.

Parameters
repeatMode

The specified repeat mode. The value can be RepeatMode::None, RepeatMode::Track, or RepeatMode::All.

Since:

BlackBerry 10.3.0

void setShuffleMode (

Used to set the value of the shuffle mode for the player.

This function sets the shuffle mode for the player. Any active controller will be notified of the current mode.

Parameters
shuffleMode

The specified repeat mode. The value can be ShuffleMode::None, or ShuffleMode::All.

Since:

BlackBerry 10.3.0

bb::multimedia::MediaError::Type trackChange ()

Used to delimit tracks with the now playing service.

Since:

BlackBerry 10.0.0

Signals

void acquired ()

This signal is emitted when the now playing service has been successfully acquired.

Since:

BlackBerry 10.0.0

void audioManagerHandleChanged (
  • unsigned intaudioManagerHandle)

This signal is emitted when the externally managed audio manager has changed.

Parameters
audioManagerHandle

The audio manager handle.

Since:

BlackBerry 10.0.0

void controllerActiveChanged (
  • boolcontrollerActive)

This signal is emitted in response to controller activity on the connection.

Parameters
controllerActive

If true one or more controllers are active on the now playing service, if false no controllers are active on the now playing service.

Since:

BlackBerry 10.0.0

void durationChanged (
  • unsigned intduration)

This signal is emitted when the duration value changes.

Parameters
duration

The duration of the current track.

Since:

BlackBerry 10.0.0

void forward ()

This signal is emitted on notification that a forward command has been received.

Since:

BlackBerry 10.0.0

void iconUrlChanged (

This signal is emitted when the icon URL value changes.

Parameters
url

The current icon location.

Since:

BlackBerry 10.0.0

void mediaStateChanged (

This signal is emitted when the media state changes.

Parameters
mediaState

The current media state being associated with the now playing connection.

Since:

BlackBerry 10.0.0

void metaDataChanged (

This signal is emitted when the metadata changes.

Parameters
metadata

The updated metadata associated with the now playing connection.

Since:

BlackBerry 10.0.0

void next ()

This signal is emitted on notification that a next track command has been received.

Since:

BlackBerry 10.0.0

void nextEnabledChanged (
  • boolnextEnabled)

This signal is emitted when setNextEnabled() is called.

Parameters
nextEnabled

A flag to indicate that the enabled flag has been toggled.

Since:

BlackBerry 10.0.0

void overlayStyleChanged (

This signal is emitted when the overlay style has been changed.

Parameters
overlayStyle

The current overlay style.

Since:

BlackBerry 10.0.0

void pause ()

This signal is emitted on notification that a pause track command has been received.

Since:

BlackBerry 10.0.0

void play ()

This signal is emitted on notification that a play track command has been received.

Since:

BlackBerry 10.0.0

void positionChanged (
  • unsigned intposition)

This signal is emitted when the position value changes.

Parameters
position

The position of the current track.

Since:

BlackBerry 10.0.0

void preemptableChanged (
  • boolpreemptable)

Deprecated.

This signal is emitted when the preemptable value changes.

The method was replaced by Priority Level approach. See PriorityLevel property documentation for details.

Parameters
preemptable

A flag indicating if the connection is preemptable or not.

Since:

BlackBerry 10.0.0

void previous ()

This signal is emitted on notification that a previous track command has been received.

Since:

BlackBerry 10.0.0

void previousEnabledChanged (
  • boolpreviousEnabled)

This signal is emitted when setPreviousEnabled() is called.

Parameters
previousEnabled

A flag to indicate that the enabled flag has been toggled.

Since:

BlackBerry 10.0.0

void repeat ()

This signal is emitted on notification that a repeat command has been received.

Since:

BlackBerry 10.3.0

void repeatModeChanged (

This signal is emitted when the player repeat value has changed.

Parameters
repeatMode

The new repeat value that the player has changed to.

Since:

BlackBerry 10.3.0

void revoked ()

This signal is emitted on notification that the connection has lost its exclusive access.

Since:

BlackBerry 10.0.0

void rewind ()

This signal is emitted on notification that a rewind command has been received.

Since:

BlackBerry 10.0.0

void shuffle ()

This signal is emitted on notification that a shuffle command has been received.

Since:

BlackBerry 10.3.0

void shuffleModeChanged (

This signal is emitted when the player shuffle value has changed.

Parameters
shuffleMode

The new shuffle value that the player has changed to.

Since:

BlackBerry 10.3.0

void stop ()

This signal is emitted on notification that a stop track command has been received.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus