Palm OS Programmer’s Companion Volume I/2-7 - project-enigma

Palm OS Programmer’s Companion Volume I/2-7

>> Site top >> Misc >> In my palm >> Palm開発ドキュメントの和訳 >> Palm OS Programmer’s Companion Volume I >> Palm OS Programmer’s Companion Volume I/2-7

最終更新日付:2014/01/01 00:00:00

← 6 節に戻る ↑2 章トップへ 8 節に進む →

2-7 ヘルパー・ノティフィケーション

 

4.0 新フィーチャセットがサポートされていれば、ヘルパー・ノティフィケーション sysNotifyHelperEvent が定義されています。このノティフィケーションは、アプリケーションが他のアプリケーションにサービスをリクエストするためのものです。Palm OS 4.0 では、ダイヤルアプリケーションだけが sysNotifyHelperEvent によるサービスを提供するアプリケーションでした。具体的には、ダイヤルアプリケーションはこのノティフィケーションに応答して電話のダイヤルを行ないます。アドレス帳はダイヤルアプリケーションを使用して、ユーザーが選択した電話番号をダイヤルします。アプリケーションから sysNotifyHelperEvent をブロードキャストすることで、同じようにダイヤルアプリケーションを利用することができます。また、サービスを提供する側を作成することもできます。

このセクションでは、sysNotifyHelperEvent ノティフィケーションに応答するアプリケーションをヘルパー、ノティフィケーションをブロードキャストする側をブロードキャスターと呼びます。

ヘルパーは sysNotifyHelperEvent の通知を登録します。このノティフィケーションハンドラでは、ヘルパーは自分が提供するサービスに関係するリクエストに応答して処理を行ないます。

アクションは、サービスの情報を提供するか、あるいはサービスを実行するためにリクエストすることを指します。sysNotifyHelperEvent の詳細情報の構造体(HelperNotifyEventType)は3つのアクションを定義しています。

可能な サービスは HelperServiceClass.h で定義され、「Palm OS Programmer’s API Reference」の 809 ページにある"ヘルパーAPI"の章で解説されています。これらのサービスは電話番号をダイヤルしたり、電子メールやSMSメッセージを送信したり、あるいはFAXを送信したりします。独自のサービスを定義したければ、そのサービスのために一意なクリエータIDを登録する必要があります。そのかわりとして、アプリケーションのクリエータIDを使うことができます。

このセクションでは、ヘルパーAPIについて説明します。ヘルパーAPIには、sysNotifyHelperEvent およびその SysNotifyParamType 構造体の notifyDetailsP メンバが指すデータ構造体が含まれています。以下のトピックがあります。

 

ヘルパー API を使う場合

4.0 新フィーチャセットがサポートされていれば、アプリケーションがハンドヘルド内の他のアプリケーションとコミュニケーションをとる方法がいくつかあります。まず、アプリケーションは他のアプリケーションに起動コードを送信(この章の「2-3 プログラムからのアプリケーション起動」を参照)できますし、エクスチェンジマネージャとローカルエクスチェンジライブラリを使って他のアプリケーションにデータを送信することもできます( Volume II の「1 オブジェクトエクスチェンジ」を参照)。あるいは、ヘルパーAPIを使用してサービスを実行するようリクエストすることもできます。状況によってどの方式を使うのが最適かを判断するのは難しいかもしれません。

ヘルパーAPIは、以下のような状況で使うのがベストです。

 

ヘルパーサービスのリクエスト

リスト 2.8 に、アプリケーションがどのようにダイヤルサービスをリクエストするかを示します。一般的に、サービスをリクエストするには以下のことをする必要があります。

 

リスト 2.8 ヘルパーサービスのリクエスト

Boolean PrvDialListDialSelected(FormType* frmP) {
    SysNotifyParamType param;
    HelperNotifyEventType details;
    HelperNotifyExecuteType execute;
    param.notifyType = sysNotifyHelperEvent;
    param.broadcaster = sysFileCAddress;
    param.notifyDetailsP = &details;
    param.handled = false;
    details.version = kHelperNotifyCurrentVersion;
    details.actionCode = kHelperNotifyActionCodeExecute;
    details.data.executeP = &execute;
    execute.serviceClassID = kHelperServiceClassIDVoiceDial;
    execute.helperAppID = 0;
    execute.dataP = FldGetTextPtr(ToolsGetFrmObjectPtr(frmP,
                                                       DialListNumberField));
    execute.displayedName = gDisplayName;
    execute.detailsP = 0;
    execute.err = errNone;
    SysNotifyBroadcast(&param);
    // Check error code
    if (!param.handled)
    // Not handled so exit the list - Unexpected error
        return true;
    else
        return (execute.err == errNone);
}

 

sysNotifyHelperEvent をブロードキャストする際、以下の点は重要なので注意してください。

 

ヘルパーの作成

ヘルパーを作成するには、以下の手順に従います。

ダイヤルアプリケーションが列挙と確認のアクションに対してどのように応答しているかをリスト 2.9 とリスト 2.10 に示します。列挙アクションがヘルパーに対し、メモリをアロケートして SysNotifyParamType パラメータブロックの notifyDetailsP が指す HelperNotifyEventType 構造体に追加するよう要求していることに注意してください。

この場合、notifyDetailsP->dataP は HelperNotifyEnumerateListType 構造体のリンクドリストになっています。各ヘルパーはサービス毎にこの構造体をアロケートし、リストの末尾に追加しなければなりません。ブロードキャスターはノティフィケーションのブロードキャストが完了した後でこれらの構造体を全て開放する責任があります。

リスト 2.9 提供されているサービスの列挙

Boolean PrvAppEnumerate(HelperNotifyEventType *helperNotifyEventP)
{
    HelperNotifyEnumerateListType* newNodeP;
    MemHandle handle;
    MemPtr stringP;
    newNodeP = MemPtrNew(sizeof(HelperNotifyEnumerateListType));

    // Get name to display in user interface.
    handle = DmGetResource(strRsc, HelperAppNameString);
    stringP = MemHandleLock(handle);
    StrCopy(newNodeP->helperAppName, stringP);
    MemHandleUnlock(handle);
    DmReleaseResource(handle);

    // Get name of service to display in UI.
    handle = DmGetResource(strRsc, HelperActionNameString);
    stringP = MemHandleLock(handle);
    StrCopy(newNodeP->actionName, stringP);
    MemHandleUnlock(handle);
    DmReleaseResource(handle);
    newNodeP->serviceClassID = kHelperServiceClassIDVoiceDial;
    newNodeP->helperAppID = kDialCreator;
    newNodeP->nextP = 0;

    // Add the new node.
    if (helperNotifyEventP->data.enumerateP == 0) {
        helperNotifyEventP->data.enumerateP = newNodeP;
    } else {
        HelperNotifyEnumerateListType* nodeP;
        nodeP = helperNotifyEventP->data.enumerateP;
        //Look for the end of the list.
        while ( nodeP->nextP != 0 )
            nodeP = nodeP->nextP;
        nodeP->nextP = newNodeP;
    }    
    return true;
}

 

リスト 2.10 では、ダイヤルアプリケーションがどのようにして確認アクションに応答しているかを示しています。

リスト 2.10 確認アクションの応答

Boolean PrvAppValidate (SysNotifyParamType *sysNotifyParamP)
{
    HelperNotifyEventType* helperNotifyEvent;
    helperNotifyEvent = sysNotifyParamP->notifyDetailsP;

    // Check version
    if (helperNotifyEvent->version < 1)
        return false;

    // Check service
    if (helperNotifyEvent-> data.validateP->serviceClassID
        != kHelperServiceClassIDVoiceDial)
        return false;

    // check appId (either null or me)
    if ((helperNotifyEvent->data.validateP->helperAppID != 0)
        && (helperNotifyEvent->data.validateP->helperAppID != kDialCreator))
        return false;

    // Check Telephony library presence
    if (!PrvAppCheckTelephony())
        return false;

    sysNotifyParamP->handled = true;
    return true;

}

 

ヘルパーを作成する場合、以下の点にも注意してください。

 

 

 

← 6 節に戻る ↑2 章トップへ 8 節に進む →

 

 


Copyright(C) 2005-2017 project-enigma.
Generated by CL-PREFAB.