/MEng/System/CQC/Runtime/CQCMediaInfo

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

MEng.System.CQC.Runtime.CQCMediaInfo provides access to the information available via CQC media repository drivers. These drivers provide a common API for getting access to details about the various music and movie data values that they store.

Since almost all of the methods of this class are talking to a repository driver behind the scenes, they will generally have as their first parameter a String parameter named Moniker, which should be the moniker of the repository driver that the method should interact with.

The general scheme for using this class is to use the CreateCursor method to create a cursor for a category or title set or artist. You will then use the Browse() method to browse through the elements provided by the obtained cursor. You can then use the information returned from the Browse() call to get more detailed information.

If you happen to know the cookie already, because perhaps it was selected by the user from a cover art browser or media category browser, then of course you can go straight to the method that provides the information you want.

Cursors should be closed when you are done with them. The repository drivers maintain a cursor cache, and you reserve a slot in that cache when you create a cursor. Until you close the cursor, it will remain. If you never close the cursor it will stay there until forced out by other clients requesting cursors, in which case the oldest still in use cursor will be closed. But still, to avoid unneeded waste of space, you should close the cursors you create. If it is for a very commonly accessed query, then the cursor is probably already in the cache, and another one is not created. You just get a reference to that existing cursor and its reference count is increased. So there is no performance benefit from not closing cursors, because if it's highly accessed it'll tend to stay alive all the time anyway. But by closing them, you do allow unused cursors to be removed.

 

Nested Types:

Enum=CQCMediaErrs
    AccessErr   : "";
    CookieFmt   : "";
EndEnum;

These are the errors that this class throws. Some have no text because they are just given the text of an underlying C++ exception that caused the error.

Enum=CQCMCookieTypes
    Category  : "Category Cookie";
    Title     : "Title Cookie";
    Collect   : "Collection Cookie";
    Item      : "Item Cookie";
EndEnum;

These are the types of cookies supported by the media system.

Enum=CQCMLocTypes
    FileCol  : "File Base Per-Collect";
    FileItem : "File Based, Per-Item";
    Changer  : "Changer Based";
EndEnum;

These are the types of media file locations that the repository supports.

Enum=CQCMediaTypes
    Movie    : "Movie";
    Music    : "Music";
    Pic      : "Picture";
EndEnum;

These are the types of media that CQC media repositories understand. It is returned in some queries to indicate the type of media found.

Enum=MediaSortOrders
    Artist  : "By Artist";
    Title   : "By Title";
    Year    : "By Year";
EndEnum;

These are the ways in which retrieved titles can be sorted.

VectorOf[String]  StrList;

This is a vector of String objects, used to return lists of names, cookies, locations, etc... You can use any vector of strings, this one is just used to indicate the parameter types.

VectorOf[Card4]  CountList;

This is a vector of Card4 objects, used to lists of counts or media ids. You can use any vector of Card4 type, this one is just used to indicate the parameter types.

 

Constructors:

Constructor();

There is just a default constructor available.

 

Final, Non-Const Methods:

CloseCursor
(
    [In] MEng.String Moniker, [In] MEng.String CursorId
);

This method will close a cursor previously opened by CreateCursor. You need to be diligent about closing cursors since otherwise they will stay open on the server. They will eventually be discarded if the server's cursor cache fills up, but it's just good citizenship to close them.

 

CreateCursor
(
    [In] MEng.String Moniker
    , [In] MEng.String Cookie
    , [In] MediaSortOrders Order
    , [Out] MEng.String OutData
    , [Out] MEng.String CursorId
)   Returns MEng.Card4;

This method will obtain a cursor from the media repository driver indicated by the Moniker parameter. The passed cookie will be either a category cookie, to browse a top level category, or a title cookie to browse the collections within a title set. You will get a cursor id back that can later be used with the Browse() method to browse through the elements available via the new cursor.

The return value indicates how many elements are available via the cursor, which you will need in order to browse through the list. The OutData will be either the category name for the indicated category cookie, or the title set name for the indicated title set cookie.

 

Final, Const Methods:

Browse
(
    [In] MEng.String Moniker
    , [In] MEng.String CursorId
    , [In] MEng.Card4 PageSz
    , [In] MEng.Card4 Index
    , [Out] StrList Cookies
    , [Out] StrList Names
    , [Out] CountList Counts
    , [Out] StrList Artists
    , [Out] CountList Years
);

Once you have obtained a cursor for some media list (category, title set, artist, etc...), you can call this method to browse through the elements of that list. You provide a starting index in the list and a page size (the max number of elements you want to receive) and get back a set of lists of the information about those elements. You may not get back the full page size's worth of elements, if there are not that many left.

If the passed index is at or beyond the end of the list, you will get an AccessErr exception. You were given the full count of available elements when you created the cursor and are expected to manage paging around within that available list.

GetCatList
(
    [In] MEng.String Moniker
    , [In] CQCMediaTypes MType
    , [In] MEng.Boolean NoEmpty
    , [Out] StrList Names
    , [Out] StrList Cookies
)   Returns MEng.Card4;

This method will return the names and cookies for all of the categories defined for the indicated media type. You can indicate whether you want to get them all, or to only get those that have at least one title defined. You will get back two vectors of strings, which contain the names and cookie. The return type indicates how many items to expect in the lists.

GetColDetails
(
    [In]    MEng.String Moniker
    , [In]  MEng.String ColCookie
    , [Out] MEng.String TitleName
    , [Out] MEng.String ColName
    , [Out] MEng.String Artist
    , [Out] MEng.String AspectRatio
    , [Out] MEng.String Cast
    , [Out] MEng.String Descr
    , [Out] MEng.String Label
    , [Out] MEng.String LeadActor
    , [Out] MEng.String Rating
    , [Out] MEng.Card4  ColNumber
    , [Out] MEng.Card4  ItemCount
    , [Out] MEng.Card4  Year
)   Returns CQCMediaTypes;

This method will get detailed information for an indicated collection. The collection cookie represents the collection for which the detail information should be obtained, and of course must be from the repository indicated by the Moniker field. If the operation succeeds, then the output parameters are filled with the collection details information, and the return type indicates the type of the media. Some output parameters only apply to particular types of media. For instance, Cast or AspectRatio are generally only used in Movie media. Note that the name of the containing title is returned as well, as a convenience.

The collection number and item count parameters refer to the number of the collection within its parent title (a 1 based number) and the number of items that the collection contains. The Rating parameter will generally be an MPAA rating, but what it contains is really up to the repository.

GetCookieType
(
    [In] MEng.String Cookie
    , [In] CQCMediaTypes MType
)   Returns CQCMCookieTypes;

This method will parse the passed cookie and, if it is correctly formatted, return the type of cookie and the media type it represents. If the cookie is badly formatted, it will throw a CookieFmt error.

GetCoverArt
(
    [In]    MEng.String Moniker
    , [In]  MEng.String Cookie
    , [In]  MEng.Boolean ForTitle
    , [Out] MEng.MemBuf ToFill
    , [Out] MEng.Card4 ImgSz
)   Returns MEng.Boolean;

This method will retrieve the cover art for the indicated cookie, which can be either a title or collection cookie. The ForTitle parameter indicates whether the passed cookie is supposed to be a title cookie or collection cookie. This could be determined automatically but this just provides an extra layer of checking. If the cookie is valid, the image data will be returned in the passed memory buffer and the number of bytes placed into the buffer is put into the ImgSz parameter.

The image will be a JPEG or PNG image, in its raw binary format, as it would be on disk.

GetItemDetails
(
    [In] MEng.String Moniker
    , [In] MEng.String ItemCookie
    , [Out] MEng.String Name
    , [Out] MEng.String Artist
    , [Out] MEng.String Loc
);

This method will return details about a single item. You provide the item cookie and it returns the item name, location information and artist. The location information might be empty if the containing collection has collection level location info.

GetItemList
(
    [In] MEng.String Moniker
    , [In] String ColCookie
    , [Out] StrList Names
    , [Out] StrList Cookies
    , [Out] StrList Locs
    , [Out] StrList Artists
)   Returns MEng.Card4;

This method will return details about the indicated collection. You provide the repository moniker and and a collection cookie. This method will return the names, cookies, locations, and artists for the items in that collection. The return will indicate how many items were found, i.e. how many entries to expect in each returned list.

GetTitleDetails
(
    [In] MEng.String Moniker
    , [In] String TitleCookie
    , [Out] MEng.Card4 ColCount
    , [Out] StrList Names
    , [Out] StrList Cookies
    , [Out] StrList Artists
)   Returns CQCMediaTypes;

This method will return details about the indicated title set. You provide the repository moniker and the title cookie and it will return how many collections are in that title set, and for each collection it will return the name of that collection, the artist for each collection, and the collection cookies for the collections.