Funzione AssocQueryStringA (shlwapi.h)

Articolo
11/20/2024

Cerca e recupera una stringa correlata all'associazione di file o protocolli 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 utilizzati per controllare la ricerca. Può essere qualsiasi combinazione di valori ASSOCF, ad eccezione del fatto che può essere incluso 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.

estensione del nome file: estensione del nome file, ad esempio .txt.
CLSID: GUID CLSID nel formato standard "{GUID}".
ProgID: ProgID di un'applicazione, ad esempio Word.Document.8.
nome eseguibile: nome del file di .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. Viene 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 la funzione viene restituita 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, viene impostato sul numero di caratteri nel buffer pszOut. Quando la funzione viene restituita 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 viene impostato sulle dimensioni necessarie 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	Successo.
E_POINTER	Il buffer pszOut è troppo piccolo per contenere l'intera stringa.
S_FALSE	pszOut è NULL. pcchOut contiene le dimensioni del buffer necessarie.

Osservazioni

Questa funzione è un wrapper per l'interfaccia IQueryAssociations. La funzione assocQueryString è progettata per semplificare il processo di utilizzo di 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 di file o ProgID, ma alcuni gestori di anteprima vengono create solo istanze per gli elementi all'interno di specifiche cartelle della shell(il gestore di anteprima MAPI è associato a tutti gli elementi provenienti dalla cartella della shell MAPI, 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 protocolli, 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

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	Finestre
intestazione	shlwapi.h
libreria	Shlwapi.lib
dll	Shlwapi.dll (versione 5.0 o successiva)

Condividi tramite