AssocQueryStringA, fonction (shlwapi.h)

  • Article

Recherche et récupère une chaîne liée à l’association de fichier ou de protocole à partir du Registre.

Syntaxe

LWSTDAPI AssocQueryStringA(
  [in]            ASSOCF   flags,
  [in]            ASSOCSTR str,
  [in]            LPCSTR   pszAssoc,
  [in, optional]  LPCSTR   pszExtra,
  [out, optional] LPSTR    pszOut,
  [in, out]       DWORD    *pcchOut
);

Paramètres

[in] flags

Type : ASSOCF

Indicateurs qui peuvent être utilisés pour contrôler la recherche. Il peut s’agir de n’importe quelle combinaison de valeurs ASSOCF , sauf qu’une seule valeur ASSOCF_INIT peut être incluse.

[in] str

Type : ASSOCSTR

Valeur ASSOCSTR qui spécifie le type de chaîne à retourner.

[in] pszAssoc

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui est utilisée pour déterminer la clé racine. Les quatre types de chaînes suivants peuvent être utilisés.

  1. Extension de nom de fichier : extension de nom de fichier, telle que .txt.
  2. CLSID : GUID CLSID au format standard « {GUID} ».
  3. ProgID : ProgID d’une application, par exemple Word. Document.8.
  4. Nom de l’exécutable : nom du fichier .exe d’une application. L’indicateur ASSOCF_OPEN_BYEXENAME doit être défini en indicateurs.

[in, optional] pszExtra

Type : LPCTSTR

Chaîne facultative terminée par un caractère Null avec des informations supplémentaires sur l’emplacement de la chaîne. Il est généralement défini sur un verbe Shell tel que open. Définissez ce paramètre sur NULL s’il n’est pas utilisé.

[out, optional] pszOut

Type : LPTSTR

Pointeur vers une chaîne terminée par null qui, lorsque cette fonction retourne correctement, reçoit la chaîne demandée. Définissez ce paramètre sur NULL pour récupérer la taille de mémoire tampon requise.

[in, out] pcchOut

Type : DWORD*

Pointeur vers une valeur qui, lors de l’appel de la fonction, est défini sur le nombre de caractères dans la mémoire tampon pszOut . Lorsque la fonction retourne correctement, la valeur est définie sur le nombre de caractères réellement placés dans la mémoire tampon.

Si l’indicateur ASSOCF_NOTRUNCATE est défini en indicateurs et que la mémoire tampon spécifiée dans pszOut est trop petite, la fonction retourne E_POINTER et la valeur est définie sur la taille requise de la mémoire tampon.

Si pszOut a la valeur NULL, la fonction retourne S_FALSE et pcchOut pointe vers la taille requise, en caractères, de la mémoire tampon.

Valeur retournée

Type : HRESULT

Retourne une valeur d’erreur COM standard, y compris les éléments suivants :

Error Signification
S_OK Réussite.
E_POINTER La mémoire tampon pszOut est trop petite pour contenir la chaîne entière.
S_FALSE pszOut a la valeur NULL. pcchOut contient la taille de mémoire tampon requise.

Remarques

Cette fonction est un wrapper pour l’interface IQueryAssociations . La fonction AssocQueryString est destinée à simplifier le processus d’utilisation de l’interface IQueryAssociations .

Une fois qu’un élément est sélectionné, l’hôte doit décider quel gestionnaire d’aperçu (le cas échéant) est disponible pour cet élément. Les gestionnaires d’aperçu sont généralement inscrits sur des extensions de nom de fichier ou ProgID, mais certains gestionnaires d’aperçu ne sont instanciés que pour les éléments dans des dossiers d’interpréteur de commandes particuliers (le gestionnaire d’aperçu MAPI est associé à tous les éléments provenant du dossier de l’interpréteur de commandes MAPI, par exemple). Par conséquent, l’hôte doit utiliser IQueryAssociations pour déterminer le gestionnaire d’aperçu à utiliser. Pour plus d’informations sur le fonctionnement des fonctions d’association de fichiers et de protocole, consultez IQueryAssociations.

Notes

L’en-tête shlwapi.h définit AssocQueryString en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête shlwapi.h
Bibliothèque Shlwapi.lib
DLL Shlwapi.dll (version 5.0 ou ultérieure)