Método IPerPropertyBrowsing::GetPredefinedStrings (ocidl.h)

Artigo
08/25/2023

Recupera uma cadeia de caracteres de descrição de matriz para os valores permitidos que a propriedade especificada pode aceitar.

Sintaxe

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

Parâmetros

[in] dispID

O identificador de expedição da propriedade .

[out] pCaStringsOut

Um ponteiro para uma estrutura de matriz contada alocada pelo chamador que contém a contagem de elementos e o endereço de uma matriz alocada pelo método de ponteiros de cadeia de caracteres. Esse método também aloca memória para os valores de cadeia de caracteres que contêm os nomes predefinidos e armazena os ponteiros de cadeia de caracteres na matriz. Se o método falhar, nenhuma memória será alocada e o conteúdo da estrutura será indefinido.

[out] pCaCookiesOut

Um ponteiro para a estrutura de matriz contada alocada pelo chamador que contém a contagem de elementos e o endereço de uma matriz alocada pelo método de valores DWORD . Os valores na matriz podem ser passados para IPerPropertyBrowsing::GetPredefinedValue para recuperar o valor associado ao nome na mesma posição de matriz dentro de pCaStringsOut. Se o método falhar, nenhuma memória será alocada e o conteúdo da estrutura será indefinido.

Retornar valor

Esse método pode retornar os valores de retorno padrão E_INVALIDARG, E_OUTOFMEMORY e E_UNEXPECTED, bem como os valores a seguir.

Código de retorno	Descrição
S_OK	O método foi concluído com sucesso.
E_NOTIMPL	Esse método não é implementado e não há suporte para nomes predefinidos.
E_POINTER	O endereço em pCaStringsOut ou pCaCookiesOut não é válido. Por exemplo, qualquer parâmetro pode ser NULL.

Comentários

Cada cadeia de caracteres retornada na matriz apontada por pCaStringsOut tem um token correspondente na matriz contada apontada por pCaCookiesOut, em que o token pode ser passado para IPerPropertyBrowsing::GetPredefinedValue para obter o valor real (um VARIANT) correspondente à cadeia de caracteres.

Usando as cadeias de caracteres predefinidas, um chamador pode obter uma lista de cadeias de caracteres para preencher elementos de interface do usuário, como uma caixa de listagem suspensa. Quando o usuário final seleciona uma dessas cadeias de caracteres como um valor a ser atribuído a uma propriedade, o chamador pode obter o valor correspondente por meio de IPerPropertyBrowsing::GetPredefinedValue.

Anotações para chamadores

As estruturas CALPOLESTR e CADWORD passadas para esse método são alocadas pelo chamador. O chamador é responsável por liberar cada cadeia de caracteres apontada da matriz CALPOLESTR , bem como a estrutura CALPOLESTR .

Toda a memória é alocada com CoTaskMemAlloc. O chamador é responsável por liberar as cadeias de caracteres e a matriz com CoTaskMemFree.

Após retornar desse método, o chamador é responsável por toda essa memória e deve liberá-la quando ela não for mais necessária. O código para conseguir isso aparece da seguinte maneira.

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

Anotações aos implementadores

O suporte para nomes e valores predefinidos não é necessário. Se o objeto não der suporte a esses nomes, retorne E_NOTIMPL desse método. Se esse método não for implementado, IPerPropertyBrowsing::GetPredefinedValue também não deverá ser implementado.

Esse método preenche os membros cElems e pElems das estruturasCADWORD e CALPOLESTR . Ele aloca as matrizes apontadas por essas estruturas com CoTaskMemAlloc e preenche essas matrizes. No caso CALPOLESTR , esse método também aloca cada cadeia de caracteres com CoTaskMemAlloc, armazenando cada ponteiro de cadeia de caracteres na matriz.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ocidl.h