/MEng/System/CQC/Runtime/CQCPLMgr

Class Information:

ClassPath:	MEng.System.CQC.Runtime.CQCPLMgr
Parent ClassPath:	MEng.Object
Copyable:	No
Final:	Yes

MEng.System.CQC.Runtime.CQCPLMgr is a convenience class that does all of the work required to maintain the sort of playlist that a standard CQC media renderer driver would need, and to do things like make next selections, remove items that have been played (jukebox mode), and so forth. So it can take a huge amount of the load of grunt work code off a renderer driver and its use is highly recommended in order to maintain consistency among renderer drivers.

This class manages a set of CQCPLItem objects, where each CQCPLItem represents one queued media item ('item' in the send that CQC media repositories define them, i.e. generally a song track in this case.) The playlist manager also keeps up with the index of the item within itself that is the active one (and it's assumed that your driver will always be playing that item.)

 

Literals:

Card4 kRenderDrv_QueryArt;
Card4 kRenderDrv_QueryItemList
Card4 kRenderDrv_QueryTitleArt

These are literal values for the 'query id' parameter of some of the backdoor driver methods that a media renderer driver has to provide. The renderer must return collection or title level art for the currently playing item, and it must return its current playlist, upon request from a client. The playlist manager provides the grunt work for all of these required queries, so you don't have to do the work yourself.

The specifics of writing a renderer driver are discussed in the driver development technical document.

String kMediaFld_CurCast
String kMediaFld_CurColArtist
String kMediaFld_CurColCookie
String kMediaFld_CurColName
String kMediaFld_CurLabel
String kMediaFld_CurLeadActor
String kMediaFld_CurDescr
String kMediaFld_CurItemName
String kMediaFld_CurItemArtist
String kMediaFld_CurItemCookie
String kMediaFld_CurItemTime
String kMediaFld_CurItemTotal
String kMediaFld_CurRating
String kMediaFld_CurTitleName
String kMediaFld_CurTitleCookie
String kMediaFld_CurYear
String kMediaFld_ClearPlaylist
String kMediaFld_DelPlaylistItem
String kMediaFld_EnqueueMedia
String kMediaFld_PlayMedia
String kMediaFld_PLSerialNum
String kMediaFld_PlaylistMode

These are literal values for the standard fields that any media renderer driver needs to provide, the information for which will be gotten from the playlist manager in almost all cases, by asking for the current playlist item.

 

Nested Types:

Enum=CQCPLMgrErrs
    AddFailed  : "";
    EmptyList  : "The playlist is empty";
    IndexErr   : "Index %(1) is not valid for the playlist";
EndEnum;

This enumeration defines the exceptions thrown by this class. Some of them are empty because the text is actually set to the underlying C++ error that occurred.

Enum=CQCPLMgrActs
    Rejected       : "Rejected";
    NoAction       : "NoAction";
    NewItem        : "NewItem";
    NewSelection   : "NewSelection";
    Stop           : "Stop";
EndEnum;

When you ask the playlist manager to do certain things, it will return on value of this type, to tell you what you should do in response to the change this caused in the playlist. These values will be described below where they are used.

Enum=CQCPLMgrSelRes
    Empty         : "Empty";
    NewItem       : "NewItem";
    NewAndChanged : "NewAndChanged";
EndEnum;

When you ask the playlist manager to make a new selection, when the previous item has finished playing, it returns one of these values to tell you the status of the playlist (which might change if you are in certain modes), and whether you should play a new item or not (it might be empty now.)

Enum=CQCPLModes
    Normal        : "Normal";
    Jukebox       : "Jukebox";
    Shuffle       : "Shuffle";
EndEnum;

This enumeration indicates the supported playlist modes that the manager can be put into, and that all renderer drivers should support if at all possible. Others may be added in the future. These control how the manager reacts to a request to select a new item. In normal mode, it just moves forward or back as asked. In jukebox mode it moves forward or back, but removes the previously played item. In shuffle mode it randomly selects a new item (until all playlist items have been played, then it starts over.)

 

Constructors:

Constructor();

There is just a default constructor available.

 

Final, Const Methods:

FormatTotalTime([Out] MEng.String ToFill);

The total time value is stored as a time stamp. This method provides a convenient way to get it formatted out into the standard 1m,2s type of format (so many minutes and so many seconds) so that you you don't have to get it out and format it yourself.

FormatPL([Out] MEng.String ToFill);

Renderer drivers are required to override the QueryTextVal method, and respond to a query id of kRenderDrv_QueryItemList by returning its playlist in a standard format (XML based.) This method will format the playlist in that required format, so you just need to pass along the output string of the query method to this method to have it filled in for you.

GetCurIndex() Returns MEng.Card4;

Returns the index of the currently selected playlist item. If the list is empty, it will return Card4.kMaxValue.

GetCurItem([Out] CQCPLItem ToFill);

Fills in the passed playlist item with the contents of the currently selected playlist item. If the list is empty, then an EmptyList exception is thrown. If it's not empty, but no selection has been made (after an initial AddMedia), then an IndexErr exception will be thrown.

GetItemAt([In] MEng.Card4 Index, [Out] CQCPLItem ToFill);

Fills in the passed playlist item with the contents of item at the indicated index. If the index is not valid for the playlist, then the IndexErr exception is thrown.

GetItemCookieAt([In] MEng.Card4 Index) Returns MEng.String;

Returns the item cookie for the item at the indicated index. If the index is not valid for the playlist, then the IndexErr exception is thrown.

GetItemCount() Returns MEng.Card4;

Returns the count of items currently in the playlist.

GetSerialNum() Returns MEng.Card4;

Renderer drivers are required to maintain a PLSerialNum field, which they increment every time the playlist changes. The playlist manager maintains the serial number for you and bumps it any time the list is changed, but you are responsible for updating your field to keep it in up to date, by calling this method and writing the returned value to your field.

GetPLMode() Returns CQCPLModes;

Returns the currently set playlist mode of this playlist manager object.

GetVerbose() Returns MEng.Boolean;

Returns the current verbosity setting on this object. You can put the playlist manager into verbose logging mode in order to diagnose problems.

HasItemPlayed([In] MEng.Card4 Index) Returns MEng.Boolean;

Indicates whether the item at the indicated index has played yet or not. This is generally not needed by external code, since the play list manager handles this, but it's there if you need it. When shuffle mode, once all items are played, then all of the played markers are cleared and it starts randomly selecting items again. If the index is not valid for the playlist, then the IndexErr exception is thrown.

IsEmpty() Returns MEng.Boolean;

Basically a convenience version of (GetItemCount() = 0), just to make your code less verbose and more readable.

 

Final, Non-Const Methods:

AddMedia
(
    [In] MEng.String RepoMoniker
    , [In] MEng.String Cookie
    , [In] MEng.Boolean Enqueue
) Returns CQCPLMgrActs;

This method is used to add new items to the playlist. It can either enqueue new items (add them to the end), or replace the current contents with new contents, based on the Enqueue parameter. You must provide the repository cookie that your renderer driver is set up to work with currently, and the cookie that you were given by the client code (via a write to the PlayMedia or EnqueueMedia fields, which also drives the value of the Enqueue parameter.)

The return will be one of the playlist manager actions, which tells you what you need to do in response to this. The options are:

• Rejected. The cookie or moniker is not valid, so you should reject the field write.
• NoAction. No action required, generally because it was an item cookie for non-enqueue mode, i.e. to select that item as the active one, but it's already the active one.
• NewItem. You need to start playing the newly selected active item (so call GetCurIndex or GetCurItem and start playing this new item.) Generally this is because it was a non-enqueue mode item cookie, to select a new active item, and that item was not already active.
• NewSelection. You need to make a new selection and start playing it. This is generally because the playlist was empty, and this new addition has now made items available to play.
• Stop. This value will not be returned by this method.

If an error occurs, the AddFailed exception will be thrown. You should update your PLSerialNum field at this point if the returned status indicates a possible change in the playlist.

RemoveByCookie(In] MEng.String ItemCookie) Returns CQCPLMgrActs;

This method can be used to remove an item from the list by its item cookie. This is usually done when client code writes to the driver's DelPLItem field. The cookie must be an item cookie. You will get a playlist manager action value, which indicates what you must do in response. The options are:

• Rejected. The cookie is not valid. You may not want to reject the field write in this case, since it's possible that the cookie was valid when the client sent the request, but the song was ending and was already removed by the time the request arrived. So probably it is best to just ignore this.
• NoAction. No action required. The item was removed, but it was not the currently playing or last item in the list, so your currently playing item is unaffected.
• NewItem. This is not returned by this method.
• NewSelection. You need to make a new selection and start playing it, because the item removed was the current one. The current index will be Card4.kMaxValue until you make a new selection.
• Stop. The item removed was the last item in the list, so you should stop all playback and go back to an idle mode.

You should update your PLSerialNum field at this point if the returned status indicates a possible change in the playlist.

RemoveItemAt(In] MEng.Card4 Index) Returns CQCPLMgrActs;

This method can be used to remove an item from the list by its index. There is generally no client driven reason this would be done, but it is available in case the driver needs it. Otherwise a playlist manager action is returned to indicate how to respond. The options are:

• NewSelection. You need to make a new selection and start playing it, because the item removed was the current one. The current index will be Card4.kMaxValue until you make a new selection.
• Stop. The item removed was the last item in the list, so you should stop all playback and go back to an idle mode.

If the index is not valid for the playlist, then the IndexErr exception will be thrown. You should update your PLSerialNum field at this point if the returned status indicates a possible change in the playlist.

Reset();

This method will reset the playlist back to default state. It will be empty, and will be in normal playlist mode. The playlist serial number will be bumped up, not reset back to the start, and you should update your PLSerialNum field with the new serial number to reflect the change.

SelectNewItem([In] MEng.Boolean Next, [Out] MEng.Card4 NewIndex) Returns CQCPLMgrSelRes;

When asked by the playlist manager (based on the returned CQCPLMgrActs value), you should call this method to select a new playlist item. You indicate whether you want to do a Next (else it's a Previous) type of selection, though this will be ignored if in a shuffle type mode. Generally you just do a Next except when the client code indicates it wants a previous type movement by writing to your transport field.

You will get back the index of the new item, and a selection result that tells you how to react. The options are:

• Empty. This operation emptied the playlist, because it was in a jukebox mode and the previous item was the last one in the list. You should stop all playback and go back into an idle mode.
• NewItem. A new item was selected. You should get the current item and start it playing.
• NewAndChanged. A new item was selected, so you should get the current item and start it playing, and the playlist was changed.

In the case of Empty and NewAndChanged, you should update your PLSerialNum field to reflect the change in the playlist.

SetMoniker([In] MEng.String ToSet);

Lets you store your driver's moniker in this object, so that it can be used in logged messages. Set it as soon as you can do so, before using this object.

SetPLMode([In] CQCPLModes ToSet);

Allows you to change the playlist mode of this playlist manager object, normally in response to a client writing to your PLMode field.

SetVerbose([In] MEng.Boolean ToSet);

Allows you to put this playlist manager object into verbose mode so that it will log more informative info, for debugging purposes.