Função WSAAsyncGetServByName (winsock2.h)

  • Artigo

A função WSAAsyncGetServByName recupera de forma assíncrona informações de serviço que correspondem a um nome de serviço e porta.

Sintaxe

HANDLE WSAAPI WSAAsyncGetServByName(
  [in]  HWND       hWnd,
  [in]  u_int      wMsg,
  [in]  const char *name,
  [in]  const char *proto,
  [out] char       *buf,
  [in]  int        buflen
);

Parâmetros

[in] hWnd

Identificador da janela que deve receber uma mensagem quando a solicitação assíncrona for concluída.

[in] wMsg

Mensagem a ser recebida quando a solicitação assíncrona for concluída.

[in] name

Ponteiro para um nome de serviço encerrado em nulo.

[in] proto

Ponteiro para um nome de protocolo. Isso pode ser NULL; nesse caso, WSAAsyncGetServByName procurará a primeira entrada de serviço para a qual s_name ou um dos s_aliases corresponde ao nome fornecido. Caso contrário, WSAAsyncGetServByName corresponde ao nome e ao proto.

[out] buf

Ponteiro para a área de dados para receber os dados servent . A área de dados deve ser maior do que o tamanho de uma estrutura servent porque a área de dados é usada pelo Windows Sockets para conter uma estrutura servent e todos os dados referenciados por membros da estrutura servent . É recomendável um buffer de bytes MAXGETHOSTSTRUCT.

[in] buflen

Tamanho da área de dados para o parâmetro buf , em bytes.

Retornar valor

O valor retornado especifica se a operação assíncrona foi iniciada com êxito. Isso não implica êxito ou falha da operação em si.

Se nenhum erro ocorrer, WSAAsyncGetServByName retornará um valor diferente de zero do tipo HANDLE que é o identificador de tarefa assíncrono para a solicitação (para não ser confundido com um HTASK do Windows). Esse valor pode ser usado de duas maneiras. Ele pode ser usado para cancelar a operação usando WSACancelAsyncRequest ou pode ser usado para corresponder operações assíncronas e mensagens de conclusão, examinando o parâmetro de mensagem wParam .

Se a operação assíncrona não puder ser iniciada, WSAAsyncServByName retornará um valor zero e um número de erro específico poderá ser recuperado chamando WSAGetLastError.

Os códigos de erro a seguir podem ser definidos quando uma janela do aplicativo recebe uma mensagem. Conforme descrito acima, eles podem ser extraídos do lParam na mensagem de resposta usando a macro WSAGETASYNCERROR .

Código do erro Significado
WSAENETDOWN
 O subsistema de rede falhou.
WSAENOBUFS
 Espaço em buffer insuficiente está disponível.
WSAEFAULT
 O parâmetro buf não está em uma parte válida do espaço de endereço do processo.
WSAHOST_NOT_FOUND
 Host de resposta autoritativa não encontrado.
WSATRY_AGAIN
 Serviço não autorizado não encontrado ou falha no servidor.
WSANO_RECOVERY
 Erros não detectáveis, o banco de dados de serviços não está acessível.
WSANO_DATA
 Nome válido, nenhum registro de dados do tipo solicitado.
 

Os erros a seguir podem ocorrer no momento da chamada de função e indicar que a operação assíncrona não pôde ser iniciada.

Código do erro Significado
WSANOTINITIALISED Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN O subsistema de rede falhou.
WSAEINPROGRESS Uma chamada do Windows Sockets 1.1 de bloqueio está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAEWOULDBLOCK A operação assíncrona não pode ser agendada no momento devido a recursos ou outras restrições na implementação do Windows Sockets.

Comentários

A função WSAAsyncGetServByName é uma versão assíncrona de getservbyname e é usada para recuperar informações de serviço correspondentes a um nome de serviço. O Windows Sockets inicia a operação e retorna ao chamador imediatamente, retornando um identificador de tarefa opaco e assíncrono que o aplicativo pode usar para identificar a operação. Quando a operação é concluída, os resultados (se houver) são copiados para o buffer fornecido pelo chamador e uma mensagem é enviada para a janela do aplicativo.

Quando a operação assíncrona é concluída, a janela do aplicativo indicada pelo parâmetro hWnd recebe a mensagem no parâmetro wMsg . O parâmetro wParam contém o identificador de tarefa assíncrono, conforme retornado pela chamada de função original. Os 16 bits altos de lParam contêm qualquer código de erro. O código de erro pode ser qualquer erro, conforme definido em Winsock2.h. Um código de erro zero indica a conclusão bem-sucedida da operação assíncrona.

Após a conclusão bem-sucedida, o buffer especificado para a chamada de função original contém uma estrutura servent . Para acessar os membros dessa estrutura, o endereço de buffer original deve ser convertido em um ponteiro de estrutura servent e acessado conforme apropriado.

Se o código de erro for WSAENOBUFS, o tamanho do buffer especificado por buflen na chamada original era muito pequeno para conter todas as informações resultantes. Nesse caso, os 16 bits baixos de lParam contêm o tamanho do buffer necessário para fornecer todas as informações necessárias. Se o aplicativo decidir que os dados parciais são inadequados, ele poderá reemissar a chamada da função WSAAsyncGetServByName com um buffer grande o suficiente para receber todas as informações desejadas (ou seja, não menor que os 16 bits baixos de lParam).

O buffer especificado para essa função é usado pelo Windows Sockets para construir uma estrutura servent junto com o conteúdo de áreas de dados referenciadas por membros da mesma estrutura servent . Para evitar o erro WSAENOBUFS , o aplicativo deve fornecer um buffer de pelo menos bytes MAXGETHOSTSTRUCT (conforme definido em Winsock2.h).

O código de erro e o comprimento do buffer devem ser extraídos do lParam usando as macros WSAGETASYNCERROR e WSAGETASYNCBUFLEN, definidas em Winsock2.h como:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

O uso dessas macros maximizará a portabilidade do código-fonte para o aplicativo.

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 winsock2.h (inclua Winsock2.h)
Biblioteca Ws2_32.lib
DLL Ws2_32.dll

Confira também

WSACancelAsyncRequest

Funções Winsock

Referência de Winsock

getservbyname