Méthode IPropertyStorage ::WriteMultiple (propidlbase.h)

Article
08/25/2023

La méthode WriteMultiple écrit un groupe de propriétés spécifié dans le jeu de propriétés actuel. Si une propriété portant un nom ou un identificateur de propriété spécifié existe déjà, elle est remplacée, même lorsque les types anciens et nouveaux pour la valeur de propriété sont différents. Si une propriété d’un nom ou d’un ID de propriété donné n’existe pas, elle est créée.

Syntaxe

HRESULT WriteMultiple(
  [in] ULONG                cpspec,
  [in] const PROPSPEC []    rgpspec,
  [in] const PROPVARIANT [] rgpropvar,
  [in] PROPID               propidNameFirst
);

Paramètres

[in] cpspec

Nombre de propriétés définies. La valeur de ce paramètre peut être définie sur zéro ; toutefois, cela va à l’encontre de l’objectif de la méthode, car aucune propriété n’est ensuite écrite.

[in] rgpspec

Tableau des ID de propriété (PROPSPEC) sur lesquels les propriétés sont définies. Celles-ci n’ont pas besoin d’être dans un ordre particulier et peuvent contenir des doublons, mais le dernier ID de propriété spécifié est celui qui prend effet. Un mélange d’ID de propriété et de noms de chaîne est autorisé.

[in] rgpropvar

Tableau (de taille cpspec) de structures PROPVARIANT qui contiennent les valeurs de propriété à écrire. Le tableau doit être de la taille spécifiée par cpspec.

[in] propidNameFirst

Valeur minimale pour les ID de propriété que la méthode doit affecter si le paramètre rgpspec spécifie des propriétés nommées par chaîne pour lesquelles il n’existe actuellement aucun ID de propriété. Si toutes les propriétés nommées par chaîne spécifiées existent déjà dans cet ensemble et ont donc déjà des ID de propriété, cette valeur est ignorée. Lorsqu’elle n’est pas ignorée, cette valeur doit être supérieure ou égale à deux et inférieure à 0x80000000. Les ID de propriété 0 et 1 et supérieurs à 0x80000000 sont réservés à une utilisation spéciale.

Valeur retournée

Cette méthode prend en charge la valeur de retour standard E_UNEXPECTED, en plus des éléments suivants :

Cette fonction peut également retourner des erreurs de système de fichiers ou des erreurs Win32 encapsulées dans un type de données HRESULT . Pour plus d’informations, consultez Stratégies de gestion des erreurs.

Remarques

Si une propriété spécifiée existe déjà, sa valeur est remplacée par celle spécifiée dans rgpspec, même lorsque les types anciens et nouveaux pour la valeur de propriété sont différents. Si la propriété spécifiée n’existe pas déjà, cette propriété est créée. Les modifications ne sont pas conservées dans le stockage sous-jacent tant que IPropertyStorage ::Commit n’a pas été appelé.

Les noms de propriétés sont stockés dans une section de dictionnaire spéciale du jeu de propriétés, qui mappe ces noms à des ID de propriété. Toutes les propriétés ont un ID, mais les noms sont facultatifs. Un nom de chaîne est fourni en spécifiant PRSPEC_LPWSTR dans le membre ulKind de la structure PROPSPEC . Si un nom de chaîne est fourni pour une propriété et que le nom n’existe pas déjà dans le dictionnaire, la méthode alloue un ID de propriété et ajoute l’ID de propriété et le nom au dictionnaire. L’ID de propriété est alloué de telle sorte qu’il n’entre pas en conflit avec d’autres ID dans le jeu de propriétés. La valeur de l’ID de propriété n’est pas inférieure à la valeur spécifiée par le paramètre propidNameFirst . Si le paramètre rgpspec spécifie des propriétés nommées par chaîne pour lesquelles il n’existe actuellement aucun ID de propriété, le paramètre propidNameFirst spécifie la valeur minimale pour les ID de propriété que la méthode WriteMultiple doit attribuer.

Lorsqu’un nouveau jeu de propriétés est créé, les propriétés de page de code spéciales (ID de propriété 1) et ID de paramètres régionaux (ID de propriété 0x80000000) sont écrites automatiquement dans le jeu de propriétés. Ces propriétés peuvent ensuite être lues, à l’aide de la méthode IPropertyStorage ::ReadMultiple , en spécifiant des ID de propriété avec les valeurs PID_CODEPAGE et PID_LOCALE définies par l’en-tête, respectivement. Si un jeu de propriétés n’est pas vide ( possède une ou plusieurs propriétés en plus des propriétés de la page de code et de l’ID de paramètres régionaux ou a un ou plusieurs noms dans son dictionnaire), les propriétés de la page de code spéciale et de l’ID de paramètres régionaux ne peuvent pas être modifiées en appelant IPropertyStorage ::WriteMultiple. Toutefois, si le jeu de propriétés est vide, l’une de ces propriétés spéciales ou les deux peuvent être modifiées.

Si un élément du tableau rgspec est défini avec une valeur PRSPEC_PROPID de 0xffffffff (PID_ILLEGAL), la valeur correspondante dans le tableau rgvar est ignorée par IPropertyStorage ::WriteMultiple. Par exemple, si cette méthode est appelée avec le paramètre cspec défini sur 3, mais que rgpspec[1].prspec est défini sur PRSPEC_PROPID et que rgpspec[1].propid a la valeur PID_ILLEGAL, seules deux propriétés sont écrites. L’élément rgpropvar[1] est ignoré silencieusement.

Utilisez la macro PropVariantInit pour initialiser les structures PROPVARIANT .

Les jeux de propriétés, sans inclure les données des propriétés non simples, sont limités à 256 Ko pour Windows NT 4.0 et versions antérieures. Pour Windows 2000, Windows XP et Windows Server 2003, les jeux de propriétés OLE sont limités à 1 Mo. Si ces limites sont dépassées, l’opération échoue et l’appelant reçoit un message d’erreur. Il n’y a aucune possibilité de fuite ou de dépassement de mémoire. Pour plus d’informations, consultez Gestion des jeux de propriétés.

Sauf si PROPSETFLAG_CASE_SENSITIVE est passé à IPropertySetStorage ::Create, les noms des jeux de propriétés ne respectent pas la casse. La spécification d’une propriété par son nom dans IPropertyStorage ::WriteMultiple entraîne une recherche qui ne respecte pas la casse des noms dans le jeu de propriétés. Pour comparer les chaînes qui ne respectent pas la casse, les paramètres régionaux des chaînes doivent être connus. Pour plus d’informations, consultez IPropertyStorage ::WritePropertyNames.

Pour plus d’informations, consultez Considérations relatives au stockage des propriétés.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	propidlbase.h (inclure Objbase.h, Propidlbase.h)
Bibliothèque	Uuid.lib
DLL	Ole32.dll