Metodo IPerPropertyBrowsing::GetPredefinedStrings (ocidl.h)

Articolo
08/25/2023

Recupera stringhe di descrizione della matrice per i valori consentiti che la proprietà specificata può accettare.

Sintassi

HRESULT GetPredefinedStrings(
  [in]  DISPID     dispID,
  [out] CALPOLESTR *pCaStringsOut,
  [out] CADWORD    *pCaCookiesOut
);

Parametri

[in] dispID

Identificatore dispatch della proprietà.

[out] pCaStringsOut

Puntatore a una struttura di matrice con conteggiata e allocata dal chiamante che contiene il numero di elementi e l'indirizzo di una matrice di puntatori stringa allocata dal metodo. Questo metodo alloca anche la memoria per i valori stringa contenenti i nomi predefiniti e archivia i puntatori di stringa nella matrice. Se il metodo ha esito negativo, non viene allocata alcuna memoria e il contenuto della struttura non è definito.

[out] pCaCookiesOut

Puntatore alla struttura di matrice con conteggiata e allocata dal chiamante che contiene il numero di elementi e l'indirizzo di una matrice allocata dal metodo di valori DWORD . I valori nella matrice possono essere passati a IPerPropertyBrowsing::GetPredefinedValue per recuperare il valore associato al nome nella stessa posizione della matrice all'interno di pCaStringsOut. Se il metodo ha esito negativo, non viene allocata alcuna memoria e il contenuto della struttura non è definito.

Valore restituito

Questo metodo può restituire i valori restituiti standard E_INVALIDARG, E_OUTOFMEMORY e E_UNEXPECTED, nonché i valori seguenti.

Codice restituito	Descrizione
S_OK	Metodo completato correttamente.
E_NOTIMPL	Questo metodo non è implementato e i nomi predefiniti non sono supportati.
E_POINTER	L'indirizzo in pCaStringsOut o pCaCookiesOut non è valido. Ad esempio, uno dei due parametri può essere NULL.

Commenti

Ogni stringa restituita nella matrice a cui punta pCaStringsOut ha un token corrispondente nella matrice con conteggiata a cui punta pCaCookiesOut, dove il token può essere passato a IPerPropertyBrowsing::GetPredefinedValue per ottenere il valore effettivo (un valore VARIANT) corrispondente alla stringa.

Usando le stringhe predefinite, un chiamante può ottenere un elenco di stringhe per popolare gli elementi dell'interfaccia utente, ad esempio una casella di riepilogo a discesa. Quando l'utente finale seleziona una di queste stringhe come valore da assegnare a una proprietà, il chiamante può quindi ottenere il valore corrispondente tramite IPerPropertyBrowsing::GetPredefinedValue.

Note ai chiamanti

Entrambe le strutture CALPOLESTR e CADWORD passate a questo metodo vengono allocate dal chiamante. Il chiamante è responsabile della liberazione di ogni stringa a cui punta la matrice CALPOLESTR e della struttura CALPOLESTR .

Tutta la memoria viene allocata con CoTaskMemAlloc. Il chiamante è responsabile della liberazione delle stringhe e della matrice con CoTaskMemFree.

Al ritorno da questo metodo, il chiamante è responsabile di tutta questa memoria e deve liberarlo quando non è più necessario. Il codice per ottenere questo risultato viene visualizzato come segue.

CALPOLESTR     castr; 
CWDWORD        cadw; 
ULONG          i; 
 
pIPerPropertyBrowsing->GetPredefinedStrings(dispID, &castr, &cadw); 
 
//...Use the strings and the cookies 
 
CoTaskMemFree((void *)cadw.pElems); 
 
for (i=0; i < castr.cElems; i++) 
    CoTaskMemFree((void *)castr.pElems[i]); 
 
CoTaskMemFree((void *)castr.pElems);

Note per gli implementatori

Il supporto per nomi e valori predefiniti non è obbligatorio. Se l'oggetto non supporta questi nomi, restituire E_NOTIMPL da questo metodo. Se questo metodo non è implementato, IPerPropertyBrowsing::GetPredefinedValue non deve essere implementato neanche.

Questo metodo riempie i membri cElems e pElems delle strutture CADWORD e CALPOLESTR . Alloca le matrici a cui puntano queste strutture con CoTaskMemAlloc e riempie tali matrici. Nel caso CALPOLESTR , questo metodo alloca anche ogni stringa con CoTaskMemAlloc, archiviando ogni puntatore stringa nella matrice.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ocidl.h

Vedi anche

CADWORD

CALPOLESTR

IPerPropertyBrowsing

Condividi tramite