Support

Tech Note #1: Launching Kinoma Player

• Updated 2004-03-22 to fix launching when more than one movie is present.
• Updated 2002-11-05 to add launching from VFS
• Initial version: 2002-07-31

Starting with version 1.1, Kinoma Player may be launched by other applications to open and play any Kinoma movie installed in main device memory. Beginning with version 1.5, Kinoma Player may also be launched to display a Kinoma movie stored anywhere on a VFS accessible storage device. This capability allows any Palm OS based application to use Kinoma Player to display video and still images encoded in the Kinoma movie format.

There are some items to keep in mind that apply to sub-launching Kinoma Player whether the movie to be displayed is stored in the main device memory or on a VFS storage device:

1. Do not assume that when Kinoma Player completes playback of the movie that the user will return to the launching application. The user can use the hard buttons or silk screen buttons on their Palm handheld to launch another application.
2. The controls and other user interface elements of Kinoma Player can be hidden by encoding the movie in Kinoma Producer by specifying a custom layout in the Advanced Settings dialog.

Playing movies from main device memory

The standard Palm OS SysUIAppSwitch function with a launch code of sysAppLaunchCmdOpenDB is used to launch Kinoma Player to open a particular movie.

The following sample code function illustrates how to use SysUIAppSwitch to play a particular Kinoma movie. The sample code function launchKinomaMovieByName takes as its argument the name of the database to open.

//-------------------------------------------
//  Calling launchKinomaMovieByName
//-------------------------------------------

// launch the Kinoma movie file named "elephants"
launchKinomaMovieByName("elephants");

//-------------------------------------------
//  The launchKinomaMovieFileByName function
//-------------------------------------------

#define kKinomaAppCreator 'KNMA'
#define kKinomaDataBaseType 'KMOV'

void launchKinomaMovieByName(char *databaseName)

{

    Err error = errNone;
    DmSearchStateType searchState;
    UInt16 appCard, movieCard;
    LocalID appID, movieID;
    Boolean firstTime;

    SysAppLaunchCmdOpenDBType *launchInfo;

    // find the Kinoma Player application

    error = DmGetNextDatabaseByTypeCreator(true, &searchState,
                    sysFileTApplication, kKinomaAppCreator, true,
                    &appCard, &appID);

    if (errNone != error) return;

    // find the Kinoma movie with the requested name

    firstTime = true;
    while (true) {
        char thisName[128];

        error = DmGetNextDatabaseByTypeCreator(firstTime, &searchState,
                    kKinomaDataBaseType, kKinomaAppCreator, false,
                    &movieCard, &movieID);

        if (errNone != error) return;

        error = DmDatabaseInfo(movieCard, movieID, thisName, NULL, NULL,
                    NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL);
        if (errNone != error) return;

        if (0 == StrCaselessCompare(databaseName, thisName))
            break

        firstTime = false;

    }

    // launch the application with the selected database
    launchInfo = (SysAppLaunchCmdOpenDBType *)
                    MemPtrNew(sizeof(SysAppLaunchCmdOpenDBType));
    if (NULL == launchInfo) return;

    MemPtrSetOwner((MemPtr)launchInfo, 0);    // SysUIAppSwitch will dispose
    launchInfo->cardNo = movieCard;
    launchInfo->dbID = movieID;

    error = SysUIAppSwitch(appCard, appID, sysAppLaunchCmdOpenDB, launchInfo);
    if (errNone != error) return;
}

 

The following notes apply to the preceding sample code:

1. The search for the movie database to open only looks at databases created by Kinoma Producer. Kinoma Player can also open databases created by gMovie which have a different type and creator.
2. The search by name is only an example. Your application can use any other means to find the database as long as it generates a card number and local ID for the movie to launch.
3. The Kinoma Player application is searched for by type and creator rather than by name. This is done to avoid a dependence on the database file name which can change for a variety of reasons including localization and version number bumps.

Playing movies from VFS storage

To launch Kinoma Player and have it open a document stored on a VFS volume, the function used is SysUIAppSwitch. However because there is no standard Palm OS launch code defined to request an application to open a file stored on VFS removable storage, Kinoma has defined an application specific launch code for this purpose: kinomaPlayerCmdOpenVFS.

The following sample code function illustrates how to use SysUIAppSwitch with the kinomaPlayerCmdOpenVFS to launch Kinoma Player to play a particular Kinoma movie stored on a VFS volume. The sample code function launchKinomaMovieFromVFS takes as its arguments the VFS index of the volume where the file is stored and the full path of the file.

//-------------------------------------------
//  Kinoma definitions for OpenVFS launch code
//-------------------------------------------

enum {
    kinomaPlayerCmdOpenVFS = sysAppLaunchCmdCustomBase
};

typedef struct {
    UInt16        volRefNum;
    Char        path[256];
} KinomaPlayerOpenVFSRecord;

//-------------------------------------------
//  Calling launchKinomaMovieFromVFS
//-------------------------------------------

// launch the Kinoma movie file stored on VFS volume with index 1,
//    and located at the path "/palm/programs/kinoma/Scratch.pdb".

launchKinomaMovieFromVFS(1, "/palm/programs/kinoma/Scratch.pdb");

//-------------------------------------------
//  The launchKinomaMovieFromVFS function
//-------------------------------------------

#define kKinomaAppCreator 'KNMA'
#define kKinomaDataBaseType 'KMOV'

void launchKinomaMovieFromVFS(UInt16 volRefNum, char *path)

{
    Err error = errNone;
    DmSearchStateType searchState;
    UInt16 appCard;
    LocalID appID;
    KinomaPlayerOpenVFSRecord *launchInfo;

    // find the Kinoma Player application

    error = DmGetNextDatabaseByTypeCreator(true, &searchState,
                    sysFileTApplication, kKinomaAppCreator, true,
                    &appCard, &appID);
    if (errNone != error) return;

    // launch the application with the selected database

    launchInfo = (KinomaPlayerOpenVFSRecord *)
                    MemPtrNew(sizeof(KinomaPlayerOpenVFSRecord));
    if (NULL == launchInfo) return;

    MemPtrSetOwner((MemPtr)launchInfo, 0);    // SysUIAppSwitch will dispose
    launchInfo->volRefNum = volRefNum;
    StrCopy(launchInfo->path, path);

    error = SysUIAppSwitch(appCard, appID, kinomaPlayerCmdOpenVFS,
            launchInfo);

    if (errNone != error) return;
}

 

The following notes apply to the preceding sample code:

1. If the specified file does not exist, Kinoma Player will immediately return control to the sub-launching application.
2. While Kinoma Player only searches for movies stored in certain directories on VFS devices, when being sub-launched using the kinomaPlayerCmdOpenVFS code the file can reside in any directory on the VFS storage device.
3. The Kinoma Player application is searched for by type and creator rather than by name. This is done to avoid a dependence on the database file name which can change for a variety of reasons including localization and version number bumps.

Legal

No license or other agreement with Kinoma, Inc. is necessary to use the technique described in this sample code. However, Kinoma Player cannot be redistributed without a license from Kinoma. For further information on licensing Kinoma Player for distribution, please send email to licensing@kinoma.com.