ウィジェット プロバイダーの ActivateApplication プロトコル

  • [アーティクル]

この記事では、ActivateApplication アクティブ化の種類を使用するウィジェット プロバイダーのコマンド ライン アクティブ化パラメーターの形式について説明します。

重要

「ウィジェット プロバイダーのパッケージ マニフェスト (XML 形式)」で説明されているように、ウィジェット プロバイダーでは、ウィジェット プロバイダー マニフェスト ファイルでアクティブ化メソッドが指定されます。 ウィジェット プロバイダーでは、CreateInstance アクティブ化の種類を使用し、ActivateApplication アクティブ化メソッドではなく、IWidgetProvider インターフェイス メソッドを使用してウィジェット ホスト要求に応答することをお勧めします。 この記事の情報は完全を期すために提供されていますが、ほとんどのウィジェット プロバイダーの実装で使用しないことをお勧めします。

ActivateApplication および base64url エンコードの引数文字列

ウィジェット プロバイダーがアクティブ化されると、コマンド ラインでは、コマンド ライン引数の base64url エンコードの前に、--widget-call= プレフィックスが付けられます。

--widget-call=[base64url]

たとえば、次の base64url の部分の場合:

--widget-call=ew0KICAgICJXaWRnZXRDYWxsIjoiQ3JlYXRlV2lkZ2V0IiwNCiAgICAiV2lkZ2V0Q29udGV4dCI6ew0KICAgICAgICAiSWQiOiI5ODU4MjEwOS1jNmJmLTQzNzItODlkNi04OWY1N2ViNzU0ZjYiLA0KICAgICAgICAiRGVmaW5pdGlvbk5hbWUiOiJQV0FfQ291bnRpbmdfV2lkZ2V0IiwNCiAgICAgICAgIlNpemUiOiJMYXJnZSINCiAgICB9DQp9

以下のようにデコードされます。

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

コマンド ライン形式の詳細

Json コマンド ラインでは、IWidgetProvider メソッドへの呼び出しがエンコードされます。

    interface IWidgetProvider
    {
        void CreateWidget(WidgetContext widgetContext);
        void DeleteWidget(String widgetId);
        void OnActionInvoked(WidgetCallInvokedArgs actionInvokedArgs);
        void OnWidgetContextChanged(WidgetContextChangedArgs contextChangedArgs);
    }

各アクティブ化は、1 つのメソッド呼び出しを表します。 Json オブジェクトには、メソッド名を指定した WidgetCall 値と、パラメーター名の名前が付けられた (ただし、大文字化されていない) 各パラメーターの値があります。 各パラメーターは、<変数名、値> のペアとして json オブジェクトにマップされます。 たとえば、CreateWidget メソッドの WidgetContext widgetContext パラメーターの場合、WidgetContext は次のように定義されます。

    runtimeclass WidgetContext
    {
        String Id { get; };
        String DefinitionId{ get; };
        String Size { get; };
    };

Note

ウィジェット プロバイダーは、将来さらにパラメーターが追加されるケースを処理するために、予期しないパラメーター値を無視する必要があります。

ウィジェット プロバイダー CreateWidget API 呼び出しは Json オブジェクトにマーシャリングされます。

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

オブジェクトには、IWidgetProvider メソッドで指定された WidgetCall 値とすべてのパラメーター値が常に含まれます。

マーシャリングされたオブジェクトの例

ウィジェットの作成 Json オブジェクト

{
    "WidgetCall":"CreateWidget",
    "WidgetContext":{
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

ウィジェットの削除 Json オブジェクト

{
  "WidgetId": "1AC74363-177B-4CD2-995F-3B25AEEA3FF4",
  "WidgetCall": "DeleteWidget",
  "CustomState": "usedata"
}

OnActionInvoked Json オブジェクト

{
    "WidgetCall": "OnActionInvoked",
    "Args":{
        "Verb": "Verb String",
        "Data": "Data Details",
        "CustomState": "usedata",
        "WidgetContext": {
            "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
            "DefinitionId":"PWA_Counting_Widget",
            "Size":"Large"
        }
    }
}

Activate Json オブジェクト

{
    "WidgetCall": "Activate",
    "WidgetContext": {
        "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
        "DefinitionId":"PWA_Counting_Widget",
        "Size":"Large"
    }
}

Deactivate Json オブジェクト

{
    "WidgetCall": "Deactivate",
    "WidgetId":"98582109-c6bf-4372-89d6-89f57eb754f6"
}

OnWidgetContextChanged Json オブジェクト

たとえば、WidgetSize が Medium に変更されます。 SV2 では、WidgetContextChanged をトリガーするのは WidgetSize だけです。

{
  "WidgetCall": "OnWidgetContextChanged",
  "Args":{
    "WidgetContext":{
            "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
            "DefinitionId":"PWA_Counting_Widget",
            "Size":"Medium"
        }
  }
}