Support

Tech Note #4: Launching Kinoma Player for Streaming Media Playback

• Initial version: September 29, 2006

Starting with version 4.0, Kinoma Player may be launched by other applications to open and play streaming media. This capability allows any Palm OS based application to use Kinoma Player 4, on a network-connected device, to stream audio and video.

There are some items to keep in mind that apply to launching Kinoma Player 4 for streaming media playback:

1. Do not assume that when Kinoma Player 4 completes playback of the stream 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. If Kinoma Player 4 is launched to open a play list which contains more than one media item, the play list is not automatically played. Instead, the play list entries are displayed in Kinoma Player 4, allowing the user to select an entry to play.

The following sample code illustrates how to use the Palm OS Exchange Manager to launch Kinoma Player 4 to play streaming media. The sample code function launchKinomaPlayerByURL takes as its arguments the streaming media URL and MIME type. The MIME type is optional, and therefore NULL can be passed for this parameter. We do however recommend passing the MIME type when known, to speed up opening the stream.

//-------------------------------------------
//  Calling launchKinomaPlayerByURL
//-------------------------------------------

// launch Kinoma Player to play media streams
launchKinomaPlayerByURL("http://www.myserver.com/song.mp3", "audio/mpeg");
launchKinomaPlayerByURL("http://www.archive.org/stream/hklw014", "video/3gpp");
launchKinomaPlayerByURL("rtsp://myserver.com/streams/live.sdp", NULL);

//-------------------------------------------
//  The launchKinomaPlayerByURL function
//-------------------------------------------

#define kKinomaAppCreator 'KNMA'

Err launchKinomaPlayerByURL(char *url, char *mime)
{
    ExgSocketType        exgSocket;
    UInt32               sizeSent;
    UInt16               appCard;

    LocalID	         appID;
    DmSearchStateType    searchState;
    char                 *pVer;
    DmOpenRef            dmRef;
    MemHandle            hRsc;
    Boolean              isKP4;

    Err                  err;

    // make sure Kinoma Player is available
    err = DmGetNextDatabaseByTypeCreator(true, &searchState,
        sysFileTApplication, kKinomaAppCreator, true, &appCard, &appID);
    if (errNone != err) goto bail;

    // make sure it's Kinoma Player 4
    dmRef = DmOpenDatabase(appCard, appID, dmModeReadOnly);
    if (0 == dmRef) {
        err = -1;
        goto bail;
    }

    hRsc = DmGet1Resource('tver', 1000);
    pVer = MemHandleLock(hRsc);
    isKP4 = (*pVer == '4');
    MemHandleUnlock(hRsc);
    DmCloseDatabase(dmRef);
    if (!isKP4) {
        err = -1;
        goto bail;
    }

    // initialize the socket
    MemSet(&exgSocket,sizeof(exgSocket),0);

    exgSocket.length = StrLen(url) + 1;

    // application to receive URL
    exgSocket.target = kKinomaAppCreator;

    // application to launch after URL received
    exgSocket.goToCreator = kKinomaAppCreator;

    // limit to local application
    exgSocket.localMode = true;

    // don't display progress
    exgSocket.noStatus = true;

    // optional MIME type

    exgSocket.type = mime;

    // send the URL
    err = ExgPut(&exgSocket);
    if (errNone == err) {
        sizeSent = ExgSend(&exgSocket, url, exgSocket.length, &err);
        ExgDisconnect(&exgSocket, err);
    }

bail:
    return err;
}

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.