Recevoir des données

  • Article

Cet article explique comment recevoir du contenu dans votre application plateforme Windows universelle (UWP) partagée à partir d’une autre application à l’aide du contrat Share. Ce contrat de partage permet à votre application d’être présentée en tant qu’option quand l’utilisateur appelle l’option Partager.

Déclarer votre application en tant que cible de partage

Le système affiche une liste des applications cibles possibles lorsqu’un utilisateur appelle Share. Pour apparaître dans la liste, votre application doit déclarer qu’elle prend en charge le contrat de partage. Cela permet au système de savoir que votre application est disponible pour recevoir du contenu.

  1. Ouvrez le fichier manifeste. Il doit être appelé quelque chose comme package.appxmanifest.
  2. Ouvrez l’onglet Déclarations .
  3. Choisissez Partager la cible dans la liste Déclarations disponibles, puis sélectionnez Ajouter.

Choisir des types de fichiers et des formats

Ensuite, choisissez les types de fichiers et les formats de données que vous prenez en charge. Les API Share prennent en charge plusieurs formats standard, tels que Text, HTML et Bitmap. Vous pouvez également spécifier des types de fichiers et des formats de données personnalisés. Si vous le faites, n’oubliez pas que les applications sources doivent savoir quels sont ces types et formats ; sinon, ces applications ne peuvent pas utiliser les formats pour partager des données.

Inscrivez-vous uniquement aux formats que votre application peut gérer. Seules les applications cibles qui prennent en charge le partage des données apparaissent lorsque l’utilisateur appelle Partager.

Pour définir des types de fichiers :

  1. Ouvrez le fichier manifeste. Il doit être appelé quelque chose comme package.appxmanifest.
  2. Dans la section Types de fichiers pris en charge de la page Déclarations , sélectionnez Ajouter nouveau.
  3. Tapez l’extension de nom de fichier que vous souhaitez prendre en charge, par exemple « .docx ». Vous devez inclure la période. Si vous souhaitez prendre en charge tous les types de fichiers, activez la case à cocher SupportsAnyFileType .

Pour définir des formats de données :

  1. Ouvrez le fichier manifeste.
  2. Ouvrez la section Formats de données de la page Déclarations , puis sélectionnez Ajouter nouveau.
  3. Tapez le nom du format de données pris en charge, par exemple « Texte ».

Gérer l’activation de partage

Lorsqu’un utilisateur sélectionne votre application (généralement en la sélectionnant dans une liste d’applications cibles disponibles dans l’interface utilisateur de partage), un événement OnShareTargetActivated est déclenché. Votre application doit gérer cet événement pour traiter les données que l’utilisateur souhaite partager.

protected override async void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
{
    // Code to handle activation goes here. 
}

Les données que l’utilisateur souhaite partager sont contenues dans un objet ShareOperation. Vous pouvez utiliser cet objet pour vérifier le format des données qu’il contient.

ShareOperation shareOperation = args.ShareOperation;
if (shareOperation.Data.Contains(StandardDataFormats.Text))
{
    string text = await shareOperation.Data.GetTextAsync();

    // To output the text from this example, you need a TextBlock control
    // with a name of "sharedContent".
    sharedContent.Text = "Text: " + text;
}

État du partage de rapports

Dans certains cas, il peut prendre du temps pour que votre application traite les données qu’elle souhaite partager. Par exemple, les utilisateurs partagent des collections de fichiers ou d’images. Ces éléments sont plus volumineux qu’une chaîne de texte simple, de sorte qu’ils prennent plus de temps à traiter.

shareOperation.ReportStarted();

Après avoir appelé ReportStarted, ne vous attendez pas à plus d’interaction utilisateur avec votre application. Par conséquent, vous ne devez pas l’appeler, sauf si votre application se trouve à un moment où elle peut être ignorée par l’utilisateur.

Avec un partage étendu, il est possible que l’utilisateur puisse ignorer l’application source avant que votre application ait toutes les données de l’objet DataPackage. Par conséquent, nous vous recommandons de vous informer du système quand votre application a acquis les données dont elle a besoin. De cette façon, le système peut suspendre ou mettre fin à l’application source si nécessaire.

shareOperation.ReportSubmittedBackgroundTask();

Si un problème se produit, appelez ReportError pour envoyer un message d’erreur au système. L’utilisateur voit le message lorsqu’il vérifie l’état du partage. À ce stade, votre application est arrêtée et le partage est terminé. L’utilisateur doit recommencer pour partager le contenu sur votre application. Selon votre scénario, vous pouvez décider qu’une erreur particulière n’est pas suffisamment grave pour mettre fin à l’opération de partage. Dans ce cas, vous pouvez choisir de ne pas appeler ReportError et de continuer avec le partage.

shareOperation.ReportError("Could not reach the server! Try again later.");

Enfin, lorsque votre application a correctement traité le contenu partagé, vous devez appeler ReportCompleted pour informer le système.

shareOperation.ReportCompleted();

Lorsque vous utilisez ces méthodes, vous les appelez généralement dans l’ordre décrit, et vous ne les appelez pas plusieurs fois. Toutefois, il arrive qu’une application cible puisse appeler ReportDataRetrieved avant ReportStarted. Par exemple, l’application peut récupérer les données dans le cadre d’une tâche dans le gestionnaire d’activation, mais pas appeler ReportStarted tant que l’utilisateur n’a pas sélectionné un bouton Partager .

Lorsqu’un utilisateur sélectionne votre application pour recevoir du contenu, nous vous recommandons de créer un Lien rapide. Un QuickLink est semblable à un raccourci qui permet aux utilisateurs de partager plus facilement des informations avec votre application. Par exemple, vous pouvez créer un QuickLink qui ouvre un nouveau message électronique préconfiguré avec l’adresse e-mail d’un ami.

Un QuickLink doit avoir un titre, une icône et un ID. Le titre (par exemple, « Email Mom ») et l’icône s’affichent lorsque l’utilisateur appuie sur l’icône Partager. L’ID est ce que votre application utilise pour accéder à toutes les informations personnalisées, telles qu’une adresse e-mail ou des informations d’identification de connexion. Lorsque votre application crée un QuickLink, l’application renvoie Le lien rapide au système en appelant ReportCompleted.

Un QuickLink ne stocke pas réellement les données. Au lieu de cela, il contient un identificateur qui, lorsqu’il est sélectionné, est envoyé à votre application. Votre application est chargée de stocker l’ID du QuickLink et les données utilisateur correspondantes. Lorsque l’utilisateur appuie sur QuickLink, vous pouvez obtenir son ID via la propriété QuickLinkId .

async void ReportCompleted(ShareOperation shareOperation, string quickLinkId, string quickLinkTitle)
{
    QuickLink quickLinkInfo = new QuickLink
    {
        Id = quickLinkId,
        Title = quickLinkTitle,

        // For quicklinks, the supported FileTypes and DataFormats are set 
        // independently from the manifest
        SupportedFileTypes = { "*" },
        SupportedDataFormats = { StandardDataFormats.Text, StandardDataFormats.Uri, 
                StandardDataFormats.Bitmap, StandardDataFormats.StorageItems }
    };

    StorageFile iconFile = await Windows.ApplicationModel.Package.Current.InstalledLocation.CreateFileAsync(
            "assets\\user.png", CreationCollisionOption.OpenIfExists);
    quickLinkInfo.Thumbnail = RandomAccessStreamReference.CreateFromFile(iconFile);
    shareOperation.ReportCompleted(quickLinkInfo);
}

Voir aussi