Função SetPropW (winuser.h)

Artigo
08/28/2023

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 SetPropW(
  [in]           HWND    hWnd,
  [in]           LPCWSTR lpString,
  [in, optional] HANDLE  hData
);

Parâmetros

[in] hWnd

Digite: 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 atom 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 retornado

Tipo: BOOL

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

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

Comentários

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 que pertença 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 window.

Observação

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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


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	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-window-l1-1-4 (introduzido no Windows 10, versão 10.0.14393)