PalmLsnSpecialLaunch

Responds to launch codes which may be device dependent.

Prototype
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.

Return value

A Palm OS error code. errNone indicates success.

Remarks

This function 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 );
}