Funzione AssocQueryStringA (shlwapi.h)

  • Articolo

Cerca e recupera una stringa correlata all'associazione di file o protocollo dal Registro di sistema.

Sintassi

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

Parametri

[in] flags

Tipo: ASSOCF

Flag che possono essere usati per controllare la ricerca. Può essere qualsiasi combinazione di valori ASSOCF , ad eccezione del fatto che è possibile includere un solo valore ASSOCF_INIT.

[in] str

Tipo: ASSOCSTR

Valore ASSOCSTR che specifica il tipo di stringa da restituire.

[in] pszAssoc

Tipo: LPCTSTR

Puntatore a una stringa con terminazione null usata per determinare la chiave radice. È possibile usare i quattro tipi di stringhe seguenti.

  1. Estensione del nome file: estensione del nome file, ad esempio .txt.
  2. CLSID: GUID CLSID nel formato standard "{GUID}".
  3. ProgID: ProgID di un'applicazione, ad esempio Word. Document.8.
  4. Nome eseguibile: nome del file .exe di un'applicazione. Il flag ASSOCF_OPEN_BYEXENAME deve essere impostato nei flag.

[in, optional] pszExtra

Tipo: LPCTSTR

Stringa con terminazione null facoltativa con informazioni aggiuntive sulla posizione della stringa. In genere è impostato su un verbo shell, ad esempio aperto. Impostare questo parametro su NULL se non viene usato.

[out, optional] pszOut

Tipo: LPTSTR

Puntatore a una stringa con terminazione null che, quando questa funzione restituisce correttamente, riceve la stringa richiesta. Impostare questo parametro su NULL per recuperare le dimensioni del buffer necessarie.

[in, out] pcchOut

Tipo: DWORD*

Puntatore a un valore che, quando si chiama la funzione, è impostato sul numero di caratteri nel buffer pszOut . Quando la funzione restituisce correttamente, il valore viene impostato sul numero di caratteri effettivamente inseriti nel buffer.

Se il flag ASSOCF_NOTRUNCATE è impostato in flag e il buffer specificato in pszOut è troppo piccolo, la funzione restituisce E_POINTER e il valore è impostato sulla dimensione necessaria del buffer.

Se pszOut è NULL, la funzione restituisce S_FALSE e pcchOut punta alle dimensioni necessarie, in caratteri, del buffer.

Valore restituito

Tipo: HRESULT

Restituisce un valore di errore COM standard, incluso quanto segue:

Errore Significato
S_OK Operazione completata.
E_POINTER Il buffer pszOut è troppo piccolo per contenere l'intera stringa.
S_FALSE pszOut è NULL. pcchOut contiene le dimensioni del buffer necessarie.

Commenti

Questa funzione è un wrapper per l'interfaccia IQueryAssociations . La funzione AssocQueryString è destinata a semplificare il processo di uso dell'interfaccia IQueryAssociations .

Dopo aver selezionato un elemento, l'host deve decidere quale gestore di anteprima (se presente) è disponibile per tale elemento. I gestori di anteprima vengono in genere registrati nelle estensioni del nome file o ProgID, ma alcuni gestori di anteprima vengono generati solo istanze per gli elementi all'interno di cartelle della shell specifiche(il gestore di anteprima MAPI è associato a qualsiasi elemento proveniente dalla cartella MAPI Shell, ad esempio). Pertanto, l'host deve usare IQueryAssociations per determinare quale gestore di anteprima usare. Per altre informazioni sul funzionamento delle funzioni di associazione di file e protocollo, vedere IQueryAssociations.

Nota

L'intestazione shlwapi.h definisce AssocQueryString come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito Valore
Client minimo supportato Windows 2000 Professional, Windows XP [solo app desktop]
Server minimo supportato Windows 2000 Server [solo app desktop]
Piattaforma di destinazione Windows
Intestazione shlwapi.h
Libreria Shlwapi.lib
DLL Shlwapi.dll (versione 5.0 o successiva)