IPerPropertyBrowsing::GetPredefinedStrings-Methode (ocidl.h)

Ruft eine Arraybeschreibungszeichenfolge für die zulässigen Werte ab, die die angegebene Eigenschaft akzeptieren kann.

Syntax

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

Parameter

[in] dispID

Der Dispatchbezeichner der Eigenschaft.

[out] pCaStringsOut

Ein Zeiger auf eine vom Aufrufer zugeordnete, gezählte Arraystruktur, die die Elementanzahl und die Adresse eines methodenseitig zugeordneten Arrays von Zeichenfolgenzeigern enthält. Diese Methode reserviert auch Arbeitsspeicher für die Zeichenfolgenwerte, die die vordefinierten Namen enthalten, und speichert die Zeichenfolgenzeiger im Array. Wenn die Methode fehlschlägt, wird kein Arbeitsspeicher zugewiesen, und der Inhalt der -Struktur ist nicht definiert.

[out] pCaCookiesOut

Ein Zeiger auf die vom Aufrufer zugeordnete, gezählte Arraystruktur, die die Elementanzahl und die Adresse eines durch die Methode zugeordneten Arrays von DWORD-Werten enthält. Die Werte im Array können an IPerPropertyBrowsing::GetPredefinedValue übergeben werden, um den dem Namen zugeordneten Wert an derselben Arrayposition in pCaStringsOut abzurufen. Wenn die Methode fehlschlägt, wird kein Arbeitsspeicher zugewiesen, und der Inhalt der -Struktur ist nicht definiert.

Rückgabewert

Diese Methode kann die Standardrückgabewerte E_INVALIDARG, E_OUTOFMEMORY und E_UNEXPECTED sowie die folgenden Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Die Methode wurde erfolgreich abgeschlossen.
E_NOTIMPL	Diese Methode ist nicht implementiert, und vordefinierte Namen werden nicht unterstützt.
E_POINTER	Die Adresse in pCaStringsOut oder pCaCookiesOut ist ungültig. Beispielsweise kann jeder Parameter NULL sein.

Hinweise

Jede Zeichenfolge, die im Array zurückgegeben wird, auf das von pCaStringsOut verwiesen wird, verfügt über ein übereinstimmendes Token im gezählten Array, auf das von pCaCookiesOut verwiesen wird, wobei das Token an IPerPropertyBrowsing::GetPredefinedValue übergeben werden kann, um den tatsächlichen Wert (ein VARIANT-Wert) abzurufen, der der Zeichenfolge entspricht.

Mithilfe der vordefinierten Zeichenfolgen kann ein Aufrufer eine Liste von Zeichenfolgen zum Auffüllen von Benutzeroberflächenelementen abrufen, z. B. ein Dropdownlistenfeld. Wenn der Endbenutzer eine dieser Zeichenfolgen als Wert auswählt, der einer Eigenschaft zugewiesen werden soll, kann der Aufrufer den entsprechenden Wert über IPerPropertyBrowsing::GetPredefinedValue abrufen.

Hinweise für Anrufer

Sowohl die CALPOLESTR - als auch die CADWORD-Struktur , die an diese Methode übergeben werden, sind aufruferseitig zugeordnet. Der Aufrufer ist für das Freigeben jeder Zeichenfolge verantwortlich, auf die aus dem CALPOLESTR-Array sowie der CALPOLESTR-Struktur verwiesen wird.

Der gesamte Arbeitsspeicher wird mit CoTaskMemAlloc zugeordnet. Der Aufrufer ist für das Freigeben der Zeichenfolgen und des Arrays mit CoTaskMemFree verantwortlich.

Nach der Rückkehr von dieser Methode ist der Aufrufer für den gesamten Arbeitsspeicher verantwortlich und muss ihn freigeben, wenn er nicht mehr benötigt wird. Der Code, um dies zu erreichen, wird wie folgt angezeigt.

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); 

Hinweise für Implementierer

Die Unterstützung für vordefinierte Namen und Werte ist nicht erforderlich. Wenn Ihr Objekt diese Namen nicht unterstützt, geben Sie E_NOTIMPL von dieser Methode zurück. Wenn diese Methode nicht implementiert ist, darf auch IPerPropertyBrowsing::GetPredefinedValue nicht implementiert werden.

Diese Methode füllt die Member cElems und pElems der CADWORD - und CALPOLESTR-Strukturen aus. Es ordnet die Arrays, auf die diese Strukturen verweisen, mit CoTaskMemAlloc zu und füllt diese Arrays aus. Im CALPOLESTR-Fall ordnet diese Methode auch jede Zeichenfolge mit CoTaskMemAlloc zu, wobei jeder Zeichenfolgenzeiger im Array gespeichert wird.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	ocidl.h

Weitere Informationen

CADWORD

CALPOLESTR

IPerPropertyBrowsing