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

Article
03/13/2024

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é avec 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 la propriété sont différents. Si une propriété d’un nom donné ou d’un ID de propriété 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’inverse 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 correspondre à 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 aucun ID de propriété n’existe actuellement. Si toutes les propriétés nommées sous forme de 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 à un usage spécial.

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 la propriété sont différents. Si la propriété spécifiée n’existe pas encore, 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 aux 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 encore 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 ne soit 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 la page de code spéciale (ID de propriété 1) et de l’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 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 codepage et d’ID de paramètres régionaux spéciaux ne peuvent pas être modifiées en appelant IPropertyStorage ::WriteMultiple. Toutefois, si le jeu de propriétés est vide, l’une ou les deux de ces propriétés spéciales 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 a la valeur PRSPEC_PROPID et que rgpspec[1].propid a la valeur PID_ILLEGAL, seules deux propriétés seront écrites. L’élément rgpropvar[1] est ignoré en silence.

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’existe aucun risque 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 sans respect de 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	propidl.h (inclure Objbase.h, Propidlbase.h)
Bibliothèque	Uuid.lib
DLL	Ole32.dll