Protocolo ActivateApplication do provedor de widget

Este artigo descreve o formato dos parâmetros de ativação da linha de comando para provedores de widgets que usam o tipo de ativação ActivateApplication.

Importante

Os provedores de widget especificam um método de ativação no arquivo de manifesto do provedor widget, conforme descrito no formato XML do manifesto do pacote do provedor widget. É recomendável que os provedores de widget usem o tipo de ativação CreateInstance e respondam às solicitações do host de widget usando os métodos da interface IWidgetProvider, em vez de usar o método de ativação ActivateApplication. As informações deste artigo são fornecidas para fins de completude e não são recomendadas para uso na maioria das implementações de provedores de widget.

Cadeia de caracteres de argumentos na codificação ActivateApplication e base64url

Quando o provedor de widget é ativado, a linha de comando terá --widget-call= prefixado antes da codificação base64url nos argumentos de linha de comando.

--widget-call=[base64url]

Por exemplo, a parte base64url em

--widget-call=ewogICAgIldpZGdldENhbGwiOiJDcmVhdGVXaWRnZXQiLAogICAgIldpZGdldENvbnRleHQiOnsKICAgICAgICAiSWQiOiI5ODU4MjEwOS1jNmJmLTQzNzItODlkNi04OWY1N2ViNzU0ZjYiLAogICAgICAgICJEZWZpbml0aW9uSWQiOiJQV0FfQ291bnRpbmdfV2lkZ2V0IiwKICAgICAgICAiU2l6ZSI6IkxhcmdlIgogICAgfQp9

é decodificado em

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

Detalhes do formato de linha de comando

A linha de comando JSON representa chamadas correspondentes aos métodos de IWidgetProvider. O pseudocódigo a seguir resume esses métodos; não é uma declaração de interface compilável.

    interface IWidgetProvider
    {
        void CreateWidget(WidgetContext widgetContext);
        void DeleteWidget(String widgetId, String customState);
        void OnActionInvoked(WidgetActionInvokedArgs actionInvokedArgs);
        void OnWidgetContextChanged(WidgetContextChangedArgs contextChangedArgs);
        void Activate(WidgetContext widgetContext);
        void Deactivate(String widgetId);
    }

Cada ativação representa uma chamada de método. O objeto JSON tem um valor WidgetCall com o nome do método e propriedades contendo os dados da chamada. Os exemplos abaixo mostram os nomes das propriedades de transporte, incluindo Args para objetos de argumento de callback.

Para um WidgetContext, o JSON contém Id, DefinitionIde Size. Id identifica uma instância de widget e DefinitionId identifica sua definição de manifesto. O JSON representa Size como uma cadeia de caracteres, como "Large"; a propriedade da API WidgetContext.Size real é uma enumeração WidgetSize, não uma cadeia de caracteres.

Note

Os provedores de widget devem ignorar valores de parâmetro inesperados para lidar com o caso em que parâmetros adicionais são adicionados no futuro.

A chamada à API do provedor CreateWidget de widget é empacotada para o objeto Json:

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

Ao lidar com argumentos de ActivateApplication, utilize o formato de transporte JSON aqui apresentado, em vez de tratar o JSON como uma declaração de interface WinRT.

Exemplos de objetos marshalled

Criar objeto Json do Widget

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

Excluir objeto Json do Widget

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

Objeto Json OnActionInvoked

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

Ativar objeto Json

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

Desativar objeto Json

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

Objeto JSON de OnWidgetContextChanged

Por exemplo, quando WidgetSize muda para Medium, um evento WidgetContextChanged é disparado.

{
  "WidgetCall": "OnWidgetContextChanged",
  "Args":{
    "WidgetContext":{
            "Id":"98582109-c6bf-4372-89d6-89f57eb754f6",
            "DefinitionId":"PWA_Counting_Widget",
            "Size":"Medium"
        }
  }
}
  • Última atualização em