Função WlanSetPsdIEDataList (wlanapi.h)
A função WlanSetPsdIeDataList define a lista de dados do elemento de informações (IE) PSD (descoberta de serviço de proximidade).
Sintaxe
DWORD WlanSetPsdIEDataList(
[in] HANDLE hClientHandle,
[in] LPCWSTR strFormat,
[in] const PWLAN_RAW_DATA_LIST pPsdIEDataList,
PVOID pReserved
);
Parâmetros
[in] hClientHandle
O identificador de sessão do cliente, obtido por uma chamada anterior para a função WlanOpenHandle .
[in] strFormat
O formato de um IE PSD na lista de dados do IE do PSD passado no parâmetro pPsdIEDataList . Essa é uma cadeia de caracteres de URI terminada em NULL que especifica o namespace do protocolo usado para descoberta.
[in] pPsdIEDataList
Um ponteiro para uma estrutura WLAN_RAW_DATA_LIST que contém a lista de dados do IE do PSD a ser definida.
pReserved
Reservado para uso futuro. Deve ser definido como NULL.
Valor retornado
Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.
Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de retorno.
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro está incorreto. Esse erro será retornado se o hClientHandle for NULL ou não for válido ou pReserved não for NULL. |
|
O identificador hClientHandle não foi encontrado na tabela de identificadores. |
|
Essa função foi chamada de uma plataforma sem suporte. Esse valor será retornado se a função tiver sido chamada de um Windows XP com SP3 ou API de LAN sem fio para Windows XP com cliente SP2. |
|
Vários códigos de erro. |
Comentários
O Protocolo de Descoberta do Serviço de Proximidade é um protocolo proprietário da Microsoft que permite que um cliente descubra serviços em sua proximidade física, que é definida pelo intervalo de rádio. A finalidade do Protocolo de Descoberta do Serviço de Proximidade é transmitir informações de descoberta de serviço, como anúncios de serviço, como parte de quadros beacon. Pontos de acesso (APs) e estações (STAs) que operam no modo ad hoc difundem periodicamente quadros de sinalizador. O quadro de sinalizador pode conter um ou vários elementos de informações proprietárias que carregam informações de descoberta relativas aos serviços oferecidos pelo dispositivo.
Um IE PSD é usado para transmitir informações compactadas fornecidas por protocolos de descoberta de nível superior para fins de descoberta passiva. Um desses protocolos de nível superior usado para descoberta é o protocolo WS-Discovery. Qualquer protocolo pode ser usado para descoberta.
O Windows Vista e o Windows Server 2008 com o Serviço de LAN Sem Fio instalado dão suporte à descoberta passiva para clientes ad hoc, serviços ad hoc e clientes de infraestrutura. Isso significa que um serviço ad hoc pode anunciar um recurso ou serviço disponível transmitindo um IE PSD em um ou mais sinalizadores. Não há nenhuma garantia de que esse sinalizador seja recebido por um cliente ad hoc ou de infraestrutura.
O Windows 7 e o Windows Server 2008 R2 com o Serviço de LAN Sem Fio instalado dão suporte à descoberta passiva para clientes ad hoc, serviços ad hoc e clientes de infraestrutura da mesma forma que no Windows Vista. Além disso, o PSD IE também tem suporte para a Rede Hospedada sem fio, um AP (ponto de acesso sem fio) baseado em software. Os aplicativos no computador local em que a Rede Hospedada sem fio deve ser executada podem usar a função WlanSetPsdIeDataList para definir o IE do PSD antes de iniciar a Rede Hospedada sem fio. Depois de definido, o IE do PSD será incluído na resposta de beacon e investigação depois que a Rede Hospedada sem fio for iniciada.
Cada aplicativo que envia ou recebe beacons mantém sua própria lista de dados do IE do PSD. O parâmetro pPsdIEDataList aponta para uma lista de IEs PSD gerados pelo aplicativo. Cada PSD IE tem o seguinte formato.
| Campo | Descrição e valor |
|---|---|
| ID do elemento (1 byte) | 221 |
| Comprimento (1 byte) | O comprimento, em bytes, do campo Dados mais 8. |
| OUI (3 bytes) | O OUI (Identificador Exclusivo Organizacional) deve conter um valor de 00-50-F2. Essa UOI pública está registrada na Microsoft. |
| Tipo DEI (1 byte) | Para o Protocolo de Descoberta do Serviço de Proximidade, o Tipo de UOI deve conter um valor de 6. |
| Hash do identificador de formato (4 bytes) | Bits 31-0 do HMAC calculados do parâmetro strFormat . |
| Dados (variável) | Contém dados definidos pelo usuário para descoberta. Esse campo não deve exceder 240 bytes de comprimento. |
O campo Hash do identificador de formato descreve o formato das informações transportadas no IE do PSD. Para garantir a exclusividade ao contornar a necessidade de administração central de identificadores de formato, uma cadeia de caracteres na forma de um URI (Uniform Resource Identifier), conforme especificado no RFC 3986, é usada para distinguir o formato. No entanto, como a transmissão deve ser eficiente e o espaço no elemento de informações é limitado, a cadeia de caracteres não é realmente transmitida, mas, em vez disso, seu hash é transmitido. No cliente, que é o lado receptor do sinalizador, o hash é correspondido com um conjunto conhecido de identificadores de formato.
O campo Hash do identificador de formato é representado por bits 0... 31 de um HMAC (código de autenticação de mensagem baseado em hash) sobre a cadeia de caracteres do identificador de formato especificada no parâmetro strFormat . O HMAC é usado para especificar o formato do campo Dados do IE do PSD. A fórmula usada para calcular o HMAC é descrita em RFC 2104. O código de exemplo para o cálculo do HMAC é conforme especificado no RFC 4634. Ao calcular o HMAC, use SHA-256 para a função de hash. A chave usada é a chave "nula" (ponteiro NULL para a chave de autenticação e chave de autenticação de comprimento zero de acordo com o código-fonte no RFC 4634). Use o valor do parâmetro strFormat (incluindo espaços, mas excluindo o caractere de terminação NULL) como o texto de entrada codificado como Unicode UTF-16 no formato little-endian.
Por exemplo, se o parâmetro strFormat for http://schemas.xmlsoaps.org/ws/2004/10/discovery, os quatro primeiros octetos do HMAC 0xF8 0xCB 0x35 0x15correspondente serão .
Se o parâmetro strFormat for http://schemas.microsoft.com/networking/discoveryformat/v2, os quatro octetos do HMAC correspondente serão 0xCF 0xF1 0x64 0x17.
Ao enviar os primeiros 4 octetos de um HMAC pela rede, envie o primeiro octeto (mais à esquerda) primeiro.
Observe que pode haver colisões nos HMACs truncados, o que significa que pode ser impossível determinar exclusivamente o protocolo de descoberta correspondente ao conteúdo de um IE PSD dos bits determinados de um HMAC. Um aplicativo que recebe um IE PSD deve fazer uma melhor suposição no protocolo de descoberta usado de um determinado HMAC e executar novamente o protocolo de descoberta de nível superior depois que uma conexão for estabelecida.
No máximo, cinco IEs de PSD podem ser passados em uma lista. Além disso, o comprimento total, em bytes, da lista de IE do PSD pode ser restrito por limitações de hardware no comprimento de um beacon.
Um aplicativo pode chamar WlanSetPsdIeDataList muitas vezes. Quando WlanSetPsdIeDataList é chamado duas vezes com o mesmo strFormat, o conteúdo do WLAN_RAW_DATA_LIST preenchido pela primeira chamada de função é substituído pelo conteúdo WLAN_RAW_DATA_LIST da segunda chamada. Quando WlanSetPsdIeDataList é chamado com o parâmetro pPsdIEDataList definido como NULL, a lista de IE do PSD associada a strFormat é desmarcada. Quando WlanSetPsdIeDataList é chamado com os parâmetros pPsdIEDataList e strFormat definidos como NULL, todas as listas de IE do PSD definidas pelo aplicativo são desmarcadas.
O serviço sem fio processa listas de dados do IE PSD definidas por diferentes aplicativos e gera blobs de dados brutos do IE. Quando um computador cria ou une uma rede ad hoc em qualquer adaptador sem fio, ele envia sinalizadores que incluem um blob de dados do IE PSD associado à rede para outros computadores.
As estações podem chamar a função WlanExtractPsdIEDataList para obter a lista de dados do IE do PSD depois de receber um sinalizador de um computador.
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 | wlanapi.h (inclua Wlanapi.h) |
| Biblioteca | Wlanapi.lib |
| DLL | Wlanapi.dll |