PalmLsnSpecialLaunch method

Responds to launch codes which may be device dependent.

Syntax
Err PalmLsnSpecialLaunch(
    UInt16   cmd,
    MemPtr   cmdPBP,
    UInt16  launchFlags
)
Parameters
  • cmd   The Palm OS application launch code.

  • cmdPBP   A pointer to a structure containing launch code parameters. If your application does not have any launch-command-specific parameters, this value is null.

  • launchFlags   Flags that indicate status information about your application.

Returns

A Palm OS error code. errNone indicates success.

Remarks

This method responds to device dependent or standard launch codes not defined as sysAppLaunchCmdNormalLaunch.

Example

The following example, used for the Treo 650 smartphone implementation, uses PalmLsnSpecialLaunch to handle Listener events:

Err PalmLsnSpecialLaunch( UInt16 cmd, MemPtr cmdPBP, UInt16 /*launchFlags*/ ) {
    switch(cmd) {
        case sysAppLaunchCmdSystemReset:
            // Fall through
        case sysAppLaunchCmdSyncNotify:
            // Fall through
        case phnLibLaunchCmdRegister:
            return registerListener();
        case phnLibLaunchCmdEvent: {
            if (!IsFeatureOn(PalmLsnGetFeature(), Listening)) {
                return(errNone);
            }
            PhnEventPtr phoneEventP = (PhnEventPtr) cmdPBP;
            if (phoneEventP->eventType == phnEvtMessageInd) {
                return(handleMessage(phoneEventP->data.params.id, &phoneEventP->acknowledge));
            }
        }
        default:
            break;
    }
    return(errNone);
}

If a message is detected, handleMessage is used to process the message into the appropriate action.

static Err handleMessage( PhnDatabaseID id, Boolean * handled )
/*************************************************************/
// This routine will construct a_palm_msg and then call
// PalmLsnProcess to process it.
{
    a_palm_msg *     ulMsg;
    Err              ret;
    Boolean          newlyLoaded;
    PhnAddressList   addrList;
    PhnAddressHandle addrH;
    MemHandle        msgBodyH;
    Char *           msgSender;
    Char *           msgBody;
    UInt32           msgTime;
    Char             configDb[ dmDBNameLength ];
    UInt16           libRef = 0;

    // CDMA workaround recommended by Handspring
    DmOpenRef        openRef = 0;

    *handled = false;

    // Allocate a message structure for passing over
    // to PalmLsnProcess later
    ulMsg = PalmLsnAllocate();
    if (ulMsg == NULL) {
        return(sysErrNoFreeRAM);
    }

    // Load the phone library   
    ret = findOrLoadPhoneLibrary(&libRef, &newlyLoaded);
    if (ret != errNone) {
        goto done;
    }
    openRef = PhnLibGetDBRef(libRef);

    // Retrieve sender of the message    
    ret = PhnLibGetAddresses(libRef, id, &addrList);
    if (ret != errNone) {
        goto done;
    }
    ret = PhnLibGetNth(libRef, addrList, 1, &addrH);
    if (ret != errNone) {
        PhnLibDisposeAddressList(libRef, addrList);
        goto done;
    }
 
    msgSender = PhnLibGetField(libRef, addrH, phnAddrFldPhone);
    if (msgSender != NULL) {
        ret = PalmLsnDupSender(ulMsg, msgSender);
        MemPtrFree(msgSender);
    }
    PhnLibDisposeAddressList( libRef, addrList );
    if (ret != errNone) {
        goto done;
    }
 
    // Retrieve message time    
    ret = PhnLibGetDate(libRef, id, &msgTime);
    if (ret != errNone) {
        goto done;
    }
    ret = PalmLsnDupTime(ulMsg, msgTime);
    if (ret != errNone) {
        goto done;
    }

    // Retrieve the entire message body  
    ret = PhnLibGetText(libRef, id, &msgBodyH);
    if (ret != errNone) {
        goto done;  
    }
    msgBody = (Char *) MemHandleLock(msgBodyH);
    ret = PalmLsnDupMessage(ulMsg, msgBody);
 
    // msgBodyH must be disposed of by the caller
    MemHandleUnlock(msgBodyH);
    MemHandleFree(msgBodyH);
    if (ret != errNone) {
        goto done;
    }

    // Get the configuration database name
    PalmLsnGetConfigFileName(configDb);

    // Call PalmLsnProcess to process the message
    ret = PalmLsnProcess(ulMsg, configDb, NULL, handled);

done:
    if (ulMsg != NULL) {
        PalmLsnFree(ulMsg);
    }
    PhnLibReleaseDBRef(libRef, openRef);

    // Unload the phone library before any possible application switch  
    if (newlyLoaded) {
        unloadPhoneLibrary(libRef);
        newlyLoaded = false;
    }
    return(ret);
}