Função SetPropA (winuser.h)

Artigo
11/20/2024

Adiciona uma nova entrada ou altera uma entrada existente na lista de propriedades da janela especificada. A função adicionará uma nova entrada à lista se a cadeia de caracteres especificada ainda não existir na lista. A nova entrada contém a cadeia de caracteres e o identificador. Caso contrário, a função substituirá o identificador atual da cadeia de caracteres pelo identificador especificado.

Sintaxe

BOOL SetPropA(
  [in]           HWND   hWnd,
  [in]           LPCSTR lpString,
  [in, optional] HANDLE hData
);

Parâmetros

[in] hWnd

Tipo: HWND

Um identificador para a janela cuja lista de propriedades recebe a nova entrada.

[in] lpString

Tipo: LPCTSTR

Uma cadeia de caracteres terminada em nulo ou um átomo que identifica uma cadeia de caracteres. Se esse parâmetro for um átomo, ele deverá ser um átomo global criado por uma chamada anterior para a função GlobalAddAtom. O átomo deve ser colocado na palavra de baixa ordem de lpString; a palavra de alta ordem deve ser zero.

[in, optional] hData

Tipo: HANDLE

Um identificador para os dados a serem copiados para a lista de propriedades. O identificador de dados pode identificar qualquer valor útil para o aplicativo.

Valor de retorno

Tipo: BOOL

Se o identificador de dados e a cadeia de caracteres forem adicionados à lista de propriedades, o valor retornado não será zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Observações

Antes que uma janela seja destruída (ou seja, antes de retornar do processamento da mensagem de WM_NCDESTROY), um aplicativo deve remover todas as entradas adicionadas à lista de propriedades. O aplicativo deve usar a função RemoveProp para remover as entradas.

SetProp está sujeito às restrições de UIPI (Isolamento de Privilégios de Interface do Usuário). Um processo só pode chamar essa função em uma janela pertencente a um processo de nível de integridade menor ou igual. Quando a UIPI bloqueia alterações de propriedade, GetLastError retornará 5.

Exemplos

Para obter um exemplo, consulte Adicionando uma propriedade de janela.

Nota

O cabeçalho winuser.h define SetProp como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winuser.h (inclua Windows.h)
biblioteca	User32.lib
de DLL	User32.dll
conjunto de API	ext-ms-win-ntuser-window-l1-1-4 (introduzido no Windows 10, versão 10.0.14393)