Click here to view and discuss this page in DocCommentXchange. In the future, you will be sent there automatically.

PalmLsnSpecialLaunch

Responds to launch codes which may be device dependent.

Err PalmLsnSpecialLaunch(
UInt16 cmd,
MemPtr cmdPBP,
UInt16 launchFlags
)

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

A Palm OS error code. errNone indicates success.

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

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

Err PalmLsnSpecialLaunch( 
/***********************/
    UInt16 cmd,
    MemPtr cmdPBP,
    UInt16 /*launchFlags*/ )
{

switch( cmd ) {

  case sysAppLaunchCmdSystemReset: 
    // Fall through


  case phnLibLaunchCmdRegister:
   break;


case phnLibLaunchCmdEvent: {
   if( !IsFeatureOn( PalmLsnGetFeature(), Listening ) ) {
      return( errNone );
   }


 PhnEventPtr phoneEventP = (PhnEventPtr)cmdPBP;


 if( phoneEventP->eventType == phnEvtMessageInd ) {
      // handle the message
      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 );
}