Função WSCSetApplicationCategory (ws2spi.h)
Sintaxe
int WSCSetApplicationCategory(
[in] LPCWSTR Path,
[in] DWORD PathLength,
[in] LPCWSTR Extra,
[in] DWORD ExtraLength,
[in] DWORD PermittedLspCategories,
[out] DWORD *pPrevPermLspCat,
[out] LPINT lpErrno
);
Parâmetros
[in] Path
Um ponteiro para uma cadeia de caracteres Unicode que contém o caminho de carga para a imagem executável do aplicativo. Essa cadeia de caracteres observa as regras usuais para resolução de caminho e pode conter cadeias de caracteres de ambiente inseridas (como %SystemRoot%).
[in] PathLength
O comprimento, em caracteres, do parâmetro Path . Esse comprimento não inclui o NULL de terminação.
[in] Extra
Um ponteiro para uma cadeia de caracteres Unicode que representa os argumentos de linha de comando usados ao iniciar o aplicativo especificado no parâmetro Path . O parâmetro Extra é usado para distinguir entre várias instâncias distintas de um aplicativo quando iniciado com uma linha de comando consistente. Isso é para dar suporte a categorizações de aplicativo diferentes para diferentes instâncias de Svchost.exe ou Rundll32.exe. Se apenas o parâmetro Path for necessário e nenhum argumento de linha de comando for necessário para distinguir ainda mais entre instâncias de um aplicativo, o parâmetro Extra deverá ser definido como NULL.
[in] ExtraLength
O comprimento, em caracteres, do parâmetro Extra . Esse comprimento não inclui o NULL de terminação.
[in] PermittedLspCategories
Um valor DWORD das categorias LSP permitidas para todas as instâncias desse aplicativo. O aplicativo é identificado pela combinação dos valores dos parâmetros Path e Extra .
[out] pPrevPermLspCat
Um ponteiro para receber o conjunto anterior de categorias LSP permitidas que foram permitidas para todas as instâncias desse aplicativo. Esse parâmetro é opcional pode ser NULL.
[out] lpErrno
Um ponteiro para o código de erro se a função falhar.
Valor retornado
Se nenhum erro ocorrer, WSCSetApplicationCategory retornará ERROR_SUCCESS (zero). Caso contrário, ele retornará SOCKET_ERROR e um código de erro específico será retornado no parâmetro lpErrno .
| Código do erro | Significado |
|---|---|
| Um ou mais argumentos não estão em uma parte válida do espaço de endereço do usuário. | |
| Um ou mais argumentos são inválidos. | |
| Ocorreu um erro não detectável. Esse erro é retornado sob várias condições, incluindo o seguinte: o usuário não tem os privilégios administrativos necessários para acessar o registro winsock ou ocorreu uma falha ao abrir uma entrada de catálogo do Winsock ou uma entrada de ID do aplicativo. |
Comentários
WSCSetApplicationCategory é usado para definir os sinalizadores de categoria LSP associados a uma instância do aplicativo. Os aplicativos podem determinar quais comportamentos LSP são aceitáveis dentro do contexto do aplicativo. Portanto, por meio da especificação de categorias LSP permitidas, um aplicativo pode permitir que apenas os provedores de serviços em camadas que implementam comportamentos aceitáveis sejam carregados.
O parâmetro Extra é necessário quando a linha de comando é usada para distinguir entre instâncias diferentes de um aplicativo ou serviço hospedado dentro do mesmo executável. Cada instância pode ter diferentes necessidades de categorização de aplicativo. Svchost.exe e Rundll32.exe são dois exemplos em que a linha de comando é necessária para diferenciar entre instâncias de processo diferentes. Para SvcHost.exe, a opção -k <svcinstance> define a instância do processo.
Para serviços, o uso do Nome do Serviço não é suficiente, pois o Catálogo winsock é global para um determinado processo e um processo pode hospedar vários serviços.
Se a função WSCSetApplicationCategory for chamada no mesmo aplicativo (o mesmo fullpath, nome EXE e parâmetros) várias vezes, as categorias serão ORed juntas. Por exemplo, se você categorizou "c:\foo.exe -param" com LSP_SYSTEM e, em seguida, chamou a função WSCSetApplicationCategory novamente com LSP_REDIRECTOR, a entrada resultante desse aplicativo contém LSP_SYSTEM | LSP_REDIRECTOR. Esse comportamento foi projetado para dar suporte a um único arquivo executável que hospeda vários aplicativos em um único EXE (os serviços do sistema Windows svchost.exe, por exemplo).
Os soquetes de janela determinam a identidade de um aplicativo e recuperam as categorias LSP permitidas durante a primeira chamada para WSAStartup. Esse será o conjunto de categorias LSP permitidas durante a instância do aplicativo. As alterações subsequentes nas categorias LSP permitidas para uma determinada identidade de aplicativo não serão coletadas até a próxima instância do aplicativo. As categorias LSP permitidas não são mutáveis durante o tempo de vida da instância do aplicativo.
Winsock 2 acomoda protocolos em camadas. Um protocolo em camadas é aquele que implementa apenas funções de comunicação de nível mais alto, enquanto depende de uma pilha de transporte subjacente para a troca real de dados com um ponto de extremidade remoto. Um exemplo de um protocolo em camadas ou um provedor de serviços em camadas seria uma camada de segurança que adiciona protocolo ao processo de estabelecimento de conexão para executar a autenticação e estabelecer um esquema de criptografia mutuamente acordado. Esse protocolo de segurança geralmente exigiria os serviços de um protocolo de transporte confiável subjacente, como TCP ou SPX. O termo protocolo base refere-se a um protocolo como TCP ou SPX que é capaz de executar comunicações de dados com um ponto de extremidade remoto. O termo protocolo em camadas é usado para descrever um protocolo que não pode ficar sozinho.
Durante a inicialização do LSP, o LSP deve fornecer ponteiros para várias funções de SPI winsock. Essas funções serão chamadas durante o processamento normal pela camada diretamente acima do LSP (outro LSP ou Ws2_32.dll).
Um LSP que implementa um IFS (sistema de arquivos) instalável pode optar seletivamente por fornecer ponteiros para funções que são implementadas por si só ou passar de volta os ponteiros fornecidos pela camada diretamente abaixo do LSP. LSPs não IFS, porque eles fornecem seus próprios identificadores, devem implementar todas as funções de SPI winsock. Isso ocorre porque cada SPI exigirá que o LSP mapeie todas as alças de soquete criadas para o identificador de soquete do provedor inferior (outro LSP ou o protocolo base).
No entanto, todos os LSPs executam seu trabalho específico fazendo processamento extra apenas em um subconjunto das funções DE SPI winsock.
É possível definir categorias LSP com base no subconjunto de funções SPI que um LSP implementa e a natureza do processamento extra executado para cada uma dessas funções.
Ao classificar LSPs, bem como classificar aplicativos que usam soquetes Winsock, torna-se possível determinar seletivamente se um LSP deve estar envolvido em um determinado processo em runtime.
No Windows Vista e posteriores, um LSP pode ser classificado com base em como ele interage com chamadas e dados do Windows Sockets. Uma categoria LSP é um grupo identificável de comportamentos em um subconjunto de funções WINSock SPI. Por exemplo, um filtro de conteúdo HTTP seria categorizado como um inspetor de dados (a categoria LSP_INSPECTOR ). A categoria LSP_INSPECTOR inspecionará (mas não alterará) parâmetros para funções SPI de transferência de dados. Um aplicativo pode consultar a categoria de um LSP e optar por não carregar o LSP com base na categoria LSP e no conjunto de categorias LSP permitidas pelo aplicativo.
A tabela a seguir lista categorias nas quais um LSP pode ser classificado.
| Categoria LSP | Descrição |
|---|---|
| **LSP_CRYPTO_COMPRESS** | O LSP é um provedor de criptografia ou compactação de dados. |
| **LSP_FIREWALL** | O LSP é um provedor de firewall. |
| **LSP_LOCAL_CACHE** | O LSP é um provedor de cache local. |
| **LSP_INBOUND_MODIFY** | O LSP modifica os dados de entrada. |
| **LSP_INSPECTOR** | O LSP inspeciona ou filtra dados. |
| **LSP_OUTBOUND_MODIFY** | O LSP modifica os dados de saída. |
| **LSP_PROXY** | O LSP atua como um proxy e redireciona pacotes. |
| **LSP_REDIRECTOR** | O LSP é um redirecionador de rede. |
| **LSP_SYSTEM** | O LSP é aceitável para uso em serviços e processos do sistema. |
Um LSP pode pertencer a mais de uma categoria. Por exemplo, um LSP de firewall/segurança pode pertencer às categorias inspetor (LSP_INSPECTOR) e firewall (LSP_FIREWALL).
Se um LSP não tiver um conjunto de categorias, ele será considerado na categoria Todos os Outros. Essa categoria LSP não será carregada em serviços ou processos do sistema (por exemplo, lsass, winlogon e muitos processos svchost).
A função WSCSetApplicationCategory só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se WSCSetApplicationCategory for chamado por um usuário que não é membro do grupo Administradores, a chamada de função falhará e WSANO_RECOVERY será retornado no parâmetro lpErrno . Essa função também pode falhar devido ao UAC (controle de conta de usuário). Se um aplicativo que contém essa função for executado por um usuário conectado como membro do grupo Administradores diferente do Administrador interno, essa chamada falhará, a menos que o aplicativo tenha sido marcado no arquivo de manifesto com um requestedExecutionLevel definido para exigirAdministrator. Se o aplicativo no Windows Vista ou no Windows Server 2008 não tiver esse arquivo de manifesto, um usuário conectado como membro do grupo Administradores que não seja o Administrador interno deverá executar o aplicativo em um shell aprimorado como administrador interno (administrador RunAs) para que essa função tenha êxito.
Qualquer instalação de arquivo ou configuração específica do provedor de serviços deve ser executada pelo chamador.
Requisitos
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | ws2spi.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |
Confira também
Categorizando aplicativos e provedores de serviços em camadas