IPerPropertyBrowsing::GetPredefinedStrings  27G.KU

Returns a counted array of string pointers (LPOLESTR pointers). The strings pointed to provide a list of names that each correspond to values that the property specified with dispID can accept.

HRESULT GetPredefinedStrings(

Parameters

dispID

[in] Dispatch identifier of the property for which the caller is requesting the string list.

pcaStringsOut

[out] Pointer to a caller-allocated, counted array structure that contains the element count and address of a method-allocated array of string pointers. This method also allocates memory for the string values containing the predefined names, and it stores the string pointers in the array. If the method fails, no memory is allocated, and the contents of the structure are undefined.

pcaCookiesOut

[out] Pointer to the caller-allocated, counted array structure that contains the element count and address of a method-allocated array of DWORDs. The DWORD values in the array can be passed to IPerPropertyBrowsing::GetPredefinedValueB7W_F8 to retrieve the value associated with the name in the same array position inside pcaStringsOut. If the method fails, no memory is allocated, and the contents of the structure are undefined.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following:

S_OK

The arrays were allocated and filled successfully.

E_NOTIMPL

This method is not implemented and predefined names are not supported.

E_POINTER

The address in pcaStringsOut or pcaCookiesOut is not valid. For example, either may be NULL.

Remarks

Each string returned in the array pointed to by pcaStringsOut has a matching token in the counted array pointed to by pcaCookiesOut, where the token can be passed to IPerPropertyBrowsing::GetPredefinedValue to get the actual value (a VARIANT) corresponding to the string.

Using the predefined strings, a caller can obtain a list of strings for populating user interface elements, such as a drop-down listbox. When the end user selects one of these strings as a value to assign to a property, the caller can then obtain the corresponding value through IPerPropertyBrowsing::GetPredefinedValue.

Notes to Callers

Both the CALPOLESTR and CADWORD structures passed to this method are caller-allocated. The caller is responsible for freeing each string pointed to from the CALPOLESTR array as well as the CALPOLESTR structure.

All memory is allocated with CoTaskMemAlloc. The caller is responsible for freeing the strings and the array with CoTaskMemFree.

Upon return from this method, the caller is responsible for all this memory and must free it when it is no longer needed. Code to achieve this appears as follows:

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

Notes to Implementers

Support for predefined names and values is not required. If your object does not support these names, return E_NOTIMPL from this method. If this method is not implemented, IPerPropertyBrowsing::GetPredefinedValue must not be implemented either.

This method fills the cElems and pElems fields of the CADWORD and CALPOLESTR structures. It allocates the arrays pointed to by these structures with CoTaskMemAlloc and fills those arrays. In the CALPOLESTR case, this method also allocates each string with CoTaskMemAlloc, storing each string pointer in the array.

See Also