Classe CAsyncSocket

Representa um Windows Socket, que é um ponto de extremidade de comunicação de rede.

Sintaxe

class CAsyncSocket : public CObject

Membros

Construtores públicos

Métodos públicos

Métodos protegidos

Operadores públicos

Membros de Dados Públicos

Comentários

A classe CAsyncSocket encapsula a API do Windows Socket Functions, fornecendo uma abstração orientada a objeto para programadores que desejam usar o Windows Sockets em conjunto com o MFC.

Essa classe baseia-se na suposição de que você entende as comunicações de rede. Você é responsável por lidar com bloqueios, diferenças de ordem de bytes e conversões entre cadeias de caracteres Unicode e MBCS (conjunto de caracteres multibyte). Se você quiser uma interface mais conveniente que gerencie esses problemas para você, consulte a classe CSocket.

Para usar um objeto CAsyncSocket, chame seu construtor e, em seguida, chame a função Create para criar o identificador de soquete subjacente (tipo SOCKET), exceto em soquetes aceitos. Para um soquete de servidor, chame a função de membro Listen e, para um soquete do cliente, chame a função de membro Connect. O soquete do servidor deve chamar a função Accept ao receber uma solicitação de conexão. Use as funções CAsyncSocket restantes para realizar comunicações entre soquetes. Após a conclusão, destrua o objeto CAsyncSocket se ele tiver sido criado no heap; o destruidor chama automaticamente a função Close. O tipo de dados SOCKET é descrito no artigo Windows Sockets: Segundo plano.

Para obter mais informações, consulte Windows Sockets: usando a classe CAsyncSocket e artigos relacionados, bem como a API do Windows Sockets 2.

Hierarquia de herança

CObject

CAsyncSocket

Requisitos

Cabeçalho: afxsock.h

CAsyncSocket::Accept

Chame essa função de membro para aceitar uma conexão em um soquete.

virtual BOOL Accept(
    CAsyncSocket& rConnectedSocket,
    SOCKADDR* lpSockAddr = NULL,
    int* lpSockAddrLen = NULL);

Parâmetros

rConnectedSocket
Uma referência que identifica um novo soquete disponível para conexão.

lpSockAddr
Um ponteiro para uma estrutura SOCKADDR que recebe o endereço do soquete de conexão, como conhecido na rede. O formato exato do argumento lpSockAddr é determinado pela família de endereços estabelecida quando o soquete foi criado. Se lpSockAddr e/ou lpSockAddrLen forem iguais a NULL, nenhuma informação sobre o endereço remoto do soquete aceito será retornada.

lpSockAddrLen
Um ponteiro para o comprimento do endereço em lpSockAddr, em bytes. O lpSockAddrLen é um parâmetro de valor-resultado: ele deve inicialmente conter a quantidade de espaço apontada por lpSockAddr; no retorno, ele conterá o comprimento real (em bytes) do endereço retornado.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT O argumento lpSockAddrLen é muito pequeno (menor que o tamanho de uma estrutura SOCKADDR).

• WSAEINPROGRESS Uma chamada de Bloqueio do Windows Sockets está em andamento.

• WSAEINVAL Listen não foi invocado antes de ser aceito.

• WSAEMFILE A fila está vazia após a entrada a ser aceita e não há descritores disponíveis.

• WSAENOBUFS Nenhum espaço de buffer disponível.

• WSAENOTSOCK O descritor não é um soquete.

• WSAEOPNOTSUPP O soquete referenciado não é um tipo que dá suporte ao serviço orientado à conexão.

• WSAEWOULDBLOCK O soquete é marcado como não desbloqueio e nenhuma conexão está presente para ser aceita.

Comentários

Essa rotina extrai a primeira conexão na fila de conexões pendentes, cria um novo soquete com as mesmas propriedades desse soquete e o anexa a rConnectedSocket. Se nenhuma conexão pendente estiver presente na fila, Accept retornará zero e GetLastError retornará um erro. O soquete aceito (rConnectedSocket) não pode ser usado para aceitar mais conexões. O soquete original permanece aberto e escutando.

O argumento lpSockAddr é um parâmetro de resultado que é preenchido com o endereço do soquete de conexão, como conhecido pela camada de comunicações. Accept é usado com tipos de soquete baseados em conexão, como SOCK_STREAM.

CAsyncSocket::AsyncSelect

Chame essa função de membro para solicitar uma notificação de evento para um soquete.

BOOL AsyncSelect(long lEvent = FD_READ | FD_WRITE | FD_OOB | FD_ACCEPT | FD_CONNECT | FD_CLOSE);

Parâmetros

lEvent
Uma máscara de bits que especifica uma combinação de eventos de rede em que o aplicativo está interessado.

• FD_READ Deseja receber uma notificação de preparação para leitura.

• FD_WRITE Deseja receber uma notificação quando os dados estiverem disponíveis para serem lidos.

• FD_OOB Deseja receber uma notificação da chegada de dados fora da banda.

• FD_ACCEPT Deseja receber uma notificação de conexões de entrada.

• FD_CONNECT Deseja receber a notificação dos resultados da conexão.

• FD_CLOSE Deseja receber uma notificação quando um soquete tiver sido fechado por um par.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEINVAL Indica que um dos parâmetros especificados era inválido.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

Comentários

Essa função é usada para especificar quais funções de notificação de retorno de chamada MFC serão chamadas para o soquete. AsyncSelect define automaticamente esse soquete como modo de não desbloqueio. Para obter mais informações, consulte o artigo Windows Sockets: notificações de soquete.

CAsyncSocket::Attach

Chame essa função de membro para anexar o identificador hSocket a um objeto CAsyncSocket.

BOOL Attach(
    SOCKET hSocket, long lEvent = FD_READ | FD_WRITE | FD_OOB | FD_ACCEPT | FD_CONNECT | FD_CLOSE);

Parâmetros

hSocket
Contém um identificador de um soquete.

lEvent
Uma máscara de bits que especifica uma combinação de eventos de rede em que o aplicativo está interessado.

• FD_READ Deseja receber uma notificação de preparação para leitura.

• FD_WRITE Deseja receber uma notificação quando os dados estiverem disponíveis para serem lidos.

• FD_OOB Deseja receber uma notificação da chegada de dados fora da banda.

• FD_ACCEPT Deseja receber uma notificação de conexões de entrada.

• FD_CONNECT Deseja receber a notificação dos resultados da conexão.

• FD_CLOSE Deseja receber uma notificação quando um soquete tiver sido fechado por um par.

Valor de retorno

Diferente de zero se a função for bem-sucedida.

Comentários

O identificador SOCKET é armazenado no membro de dados do objeto m_hSocket.

CAsyncSocket::Bind

Chame essa função de membro para associar um endereço local ao soquete.

BOOL Bind(
    UINT nSocketPort,
    LPCTSTR lpszSocketAddress = NULL);

BOOL Bind (
    const SOCKADDR* lpSockAddr,
    int nSockAddrLen);

Parâmetros

nSocketPort
A porta que identifica o aplicativo de soquete.

lpszSocketAddress
O endereço de rede, um número separado por pontos, como "128.56.22.8". Passar a cadeia de caracteres NULL para esse parâmetro indica que a instância CAsyncSocket deve escutar a atividade do cliente em todos os interfaces de rede.

lpSockAddr
Um ponteiro para uma estrutura SOCKADDR que contém o endereço a ser atribuído a esse soquete.

nSockAddrLen
O comprimento do endereço em lpSockAddr, em bytes.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. A lista a seguir aborda alguns dos erros que podem ser retornados. Para obter uma lista completa, consulte Códigos de erro do Windows Sockets.

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEADDRINUSE O endereço especificado já está sendo usado. (Consulte a opção de soquete SO_REUSEADDR em SetSockOpt.)

• WSAEFAULT O argumento nSockAddrLen é muito pequeno (menor que o tamanho de uma estrutura SOCKADDR).

• WSAEINPROGRESS Uma chamada de Bloqueio do Windows Sockets está em andamento.

• WSAEAFNOSUPPORTA família de endereços especificada não tem suporte nessa porta.

• WSAEINVAL O soquete já está associado a um endereço.

• WSAENOBUFS Não há buffers suficientes disponíveis; muitas conexões.

• WSAENOTSOCK O descritor não é um soquete.

Comentários

Essa rotina é usada em um datagrama não conectado ou soquete de fluxo, antes de chamadas subsequentes Connect ou Listen. Antes de aceitar solicitações de conexão, um soquete do servidor ouvinte deve selecionar um número de porta e torná-lo conhecido pelo Windows Sockets chamando Bind. Bind estabelece a associação local (endereço do host/número da porta) do soquete atribuindo um nome local a um soquete sem nome.

CAsyncSocket::CAsyncSocket

Constrói um objeto de soquete em branco.

CAsyncSocket();

Comentários

Depois de construir o objeto, você deve chamar sua função de membro Create para criar a estrutura de dados SOCKET e associar seu endereço. (No lado do servidor de uma comunicação do Windows Sockets, quando o soquete de escuta cria um soquete a ser usado na chamada Accept, você não chama Create para esse soquete.)

CAsyncSocket::Close

Fecha o soquete.

virtual void Close();

Comentários

Essa função libera o descritor de soquete para que outras referências a ele falhem com o erro WSAENOTSOCK. Se essa for a última referência ao soquete subjacente, as informações de nomenclatura associadas e os dados enfileirados serão descartados. O destruidor do objeto de soquete chama Close para você.

Para CAsyncSocket, mas não para CSocket, a semântica de Close é afetada pelas opções de soquete SO_LINGER e SO_DONTLINGER. Para obter mais informações, consulte a função de membro GetSockOpt.

CAsyncSocket::Connect

Chame essa função de membro para estabelecer uma conexão com um fluxo não conectado ou soquete de datagrama.

BOOL Connect(
    LPCTSTR lpszHostAddress,
    UINT nHostPort);

BOOL Connect(
    const SOCKADDR* lpSockAddr,
    int nSockAddrLen);

Parâmetros

lpszHostAddress
O endereço de rede do soquete ao qual esse objeto está conectado: um nome de computador como "ftp.microsoft.com" ou um número pontilhado, como "128.56.22.8".

nHostPort
A porta que identifica o aplicativo de soquete.

lpSockAddr
Um ponteiro para uma estrutura SOCKADDR que contém o endereço do soquete conectado.

nSockAddrLen
O comprimento do endereço em lpSockAddr, em bytes.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Se isso indicar um código de erro WSAEWOULDBLOCK e seu aplicativo estiver usando os retornos de chamada substituíveis, seu aplicativo receberá uma mensagem OnConnect quando a operação de conexão for concluída. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEADDRINUSE O endereço especificado já está sendo usado.

• WSAEINPROGRESS Uma chamada de Bloqueio do Windows Sockets está em andamento.

• WSAEADDRNOTAVAIL O endereço especificado não está disponível no computador local.

• WSAEAFNOSUPPORT Os endereços na família especificada não podem ser usados com este soquete.

• WSAECONNREFUSED A tentativa de conexão foi rejeitada.

• WSAEDESTADDRREQ Endereço de destino necessário.

• WSAEFAULT O argumento nSockAddrLen está incorreto.

• WSAEINVAL Endereço de host inválido.

• WSAEISCONN O soquete já está conectado.

• WSAEMFILE Nenhum outro descritor de arquivo disponível.

• WSAENETUNREACH A rede não pode ser alcançada através desse host neste momento.

• WSAENOBUFS Nenhum espaço de buffer disponível. O soquete não pode ser conectado.

• WSAENOTSOCK O descritor não é um soquete.

• WSAETIMEDOUT Tente se conectar com o tempo limite sem estabelecer uma conexão.

• WSAEWOULDBLOCK O soquete é marcado como de não desbloqueio e a conexão não pode ser concluída imediatamente.

Comentários

Se o soquete estiver desvinculado, os valores exclusivos serão atribuídos à associação local pelo sistema e o soquete será marcado como associado. Observe que, se o campo de endereço da estrutura de nomes for todos zeros, Connect retornará zero. Para obter outras informações sobre o erro, chame a função de membro GetLastError.

Para soquetes de fluxo (tipo SOCK_STREAM), uma conexão ativa é iniciada para o host estrangeiro. Quando a chamada de soquete for concluída com êxito, o soquete estará pronto para enviar/receber dados.

Para um soquete de datagrama (tipo SOCK_DGRAM), um destino padrão é definido, que será usado em chamadas subsequentes Send e Receive.

CAsyncSocket::Create

Chame a função de membro Create depois de construir um objeto de soquete para criar o soquete do Windows e anexá-lo.

BOOL Create(
    UINT nSocketPort = 0,
    int nSocketType = SOCK_STREAM,
    long lEvent = FD_READ | FD_WRITE | FD_OOB | FD_ACCEPT | FD_CONNECT | FD_CLOSE,
    LPCTSTR lpszSocketAddress = NULL);

Parâmetros

nSocketPort
Uma porta conhecida a ser usada com o soquete, ou 0 se você quiser que o Windows Socket selecione uma porta.

nSocketType
SOCK_STREAM ou SOCK_DGRAM.

lEvent
Uma máscara de bits que especifica uma combinação de eventos de rede em que o aplicativo está interessado.

• FD_READ Deseja receber uma notificação de preparação para leitura.

• FD_WRITE Deseja receber uma notificação de preparação para escrita.

• FD_OOB Deseja receber uma notificação da chegada de dados fora da banda.

• FD_ACCEPT Deseja receber uma notificação de conexões de entrada.

• FD_CONNECT Deseja receber notificação de conexão concluída.

• FD_CLOSE Deseja receber uma notificação de fechamento do soquete.

lpszSockAddress
Um ponteiro para uma cadeia de caracteres que contém o endereço de rede do soquete conectado, um número separado por pontos, como "128.56.22.8". Passar a cadeia de caracteres NULL para esse parâmetro indica que a instância CAsyncSocket deve escutar a atividade do cliente em todos os interfaces de rede.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEAFNOSUPPORTA família de endereços especificada não tem suporte.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAEMFILE Nenhum outro descritor de arquivo disponível.

• WSAENOBUFS Nenhum espaço de buffer disponível. O soquete não pode ser criado.

• WSAEPROTONOSUPPORT A porta especificada não é suportada.

• WSAEPROTOTYPE A porta especificada é o tipo errado para este soquete.

• WSAESOCKTNOSUPPORT O suporte para o tipo de soquete especificado não tem suporte nessa família de endereços.

Comentários

Create chama Socket e, se bem-sucedido, chama Bind para associar o soquete ao endereço especificado. Há suporte para os seguintes tipos de soquete:

• SOCK_STREAM Fornece fluxos de bytes baseados em conexão sequenciados, confiáveis e totalmente duplex. Usa o Protocolo de Controle de Transmissão (TCP) para a família de endereços da Internet.

• SOCK_DGRAM Suporta datagramas, que são pacotes sem conexão e não confiáveis de um comprimento máximo fixo (normalmente pequeno). Usa o UDP (User Datagram Protocol) para a família de endereços da Internet.

  Observação

  A função membro Accept faz uma referência a um novo objeto CSocket vazio como seu parâmetro. Você deve construir esse objeto antes de chamar Accept. Tenha em mente que, se esse objeto de soquete ficar fora do escopo, a conexão será fechada. Não chame Create para esse novo objeto de soquete.

Para obter mais informações sobre soquetes de fluxo e datagrama, consulte os artigos Windows Sockets: Soquetes em segundo plano, Windows Sockets: Endereços de portas e soquetes e API do Windows Sockets 2.

CAsyncSocket::CreateEx

Chame a função de membro CreateEx depois de construir um objeto de soquete para criar o soquete do Windows e anexá-lo.

Use essa função quando precisar fornecer opções avançadas, como o tipo de soquete.

BOOL CreateEx(
    ADDRINFOT* pAI,
    long lEvent = FD_READ | FD_WRITE | FD_OOB | FD_ACCEPT | FD_CONNECT | FD_CLOSE);

Parâmetros

pAI
Um ponteiro para um ADDRINFOT para conter informações de soquete, como a família e o tipo de soquete.

lEvent
Uma máscara de bits que especifica uma combinação de eventos de rede em que o aplicativo está interessado.

• FD_READ Deseja receber uma notificação de preparação para leitura.

• FD_WRITE Deseja receber uma notificação de preparação para escrita.

• FD_OOB Deseja receber uma notificação da chegada de dados fora da banda.

• FD_ACCEPT Deseja receber uma notificação de conexões de entrada.

• FD_CONNECT Deseja receber notificação de conexão concluída.

• FD_CLOSE Deseja receber uma notificação de fechamento do soquete.

Valor de retorno

Consulte o valor retornado para Create().

Comentários

Consulte os comentário de Create().

CAsyncSocket::Detach

Chame essa função de membro para desanexar o identificador SOCKET no membro de dados m_hSocket do objeto CAsyncSocket e defina m_hSocket como NULL.

SOCKET Detach();

CAsyncSocket::FromHandle

Um ponteiro para um objeto CAsyncSocket.

static CAsyncSocket* PASCAL FromHandle(SOCKET hSocket);

Parâmetros

hSocket
Contém um identificador de um soquete.

Valor de retorno

Um ponteiro para um objeto CAsyncSocket, ou NULL se não houver nenhum objeto CAsyncSocket anexado a hSocket.

Comentários

Quando um identificador SOCKET for fornecido, se um objeto CAsyncSocket não estiver anexado ao identificador, a função de membro retornará NULL.

CAsyncSocket::GetLastError

Chame essa função de membro para obter o status de erro da última operação que falhou.

static int PASCAL GetLastError();

Valor de retorno

O valor retornado indica o código de erro para a última rotina de API de Soquetes do Windows executada por esse thread.

Comentários

Quando uma função membro específica indica que ocorreu um erro, GetLastError deve ser chamado para recuperar o código de erro apropriado. Consulte as descrições de função de membro individual para obter uma lista de códigos de erro aplicáveis.

Para obter mais informações sobre os códigos de erro, consulte a API do Windows Sockets 2.

CAsyncSocket::GetPeerName

Chame essa função de membro para obter o endereço do soquete par ao qual esse soquete está conectado.

BOOL GetPeerName(
    CString& rPeerAddress,
    UINT& rPeerPort);

BOOL GetPeerName(
    SOCKADDR* lpSockAddr,
    int* lpSockAddrLen);

Parâmetros

rPeerAddress
Referência a um objeto CString que recebe um endereço IP separado por pontos.

rPeerPort
Referência a um UINT que armazena uma porta.

lpSockAddr
Um ponteiro para a estrutura SOCKADDR que recebe o nome do soquete par.

lpSockAddrLen
Um ponteiro para o comprimento do endereço em lpSockAddr, em bytes. No retorno, o argumento lpSockAddrLen contém o tamanho real de lpSockAddr retornado em bytes.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT O argumento lpSockAddrLen não é grande o suficiente.

• WSAEINPROGRESS Uma chamada de Bloqueio do Windows Sockets está em andamento.

• WSAENOTCONN O soquete não está conectado.

• WSAENOTSOCK O descritor não é um soquete.

Comentários

Para lidar com endereços IPv6, use CAsyncSocket::GetPeerNameEx.

CAsyncSocket::GetPeerNameEx

Chame essa função de membro para obter o endereço do soquete par ao qual esse soquete está conectado (lida com endereços IPv6).

BOOL GetPeerNameEx(
    CString& rPeerAddress,
    UINT& rPeerPort);

Parâmetros

rPeerAddress
Referência a um objeto CString que recebe um endereço IP separado por pontos.

rPeerPort
Referência a um UINT que armazena uma porta.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT O argumento lpSockAddrLen não é grande o suficiente.

• WSAEINPROGRESS Uma chamada de Bloqueio do Windows Sockets está em andamento.

• WSAENOTCONN O soquete não está conectado.

• WSAENOTSOCK O descritor não é um soquete.

Comentários

Essa função é a mesma que CAsyncSocket::GetPeerName, exceto que ela manipula endereços IPv6, bem como protocolos mais antigos.

CAsyncSocket::GetSockName

Chame essa função de membro para obter o nome local de um soquete.

BOOL GetSockName(
    CString& rSocketAddress,
    UINT& rSocketPort);

BOOL GetSockName(
    SOCKADDR* lpSockAddr,
    int* lpSockAddrLen);

Parâmetros

rSocketAddress
Referência a um objeto CString que recebe um endereço IP separado por pontos.

rSocketPort
Referência a um UINT que armazena uma porta.

lpSockAddr
Um ponteiro para uma estrutura SOCKADDR que recebe o endereço do soquete.

lpSockAddrLen
Um ponteiro para o comprimento do endereço em lpSockAddr, em bytes.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT O argumento lpSockAddrLen não é grande o suficiente.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAENOTSOCK O descritor não é um soquete.

• WSAEINVAL O soquete não foi associado a um endereço com Bind.

Comentários

Essa chamada é especialmente útil quando uma chamada Connect foi feita sem fazer uma chamada Bind primeiro; essa chamada fornece os únicos meios pelos quais você pode determinar a associação local que foi definida pelo sistema.

Para lidar com endereços IPv6, use CAsyncSocket::GetSockNameEx.

CAsyncSocket::GetSockNameEx

Chame essa função de membro para obter o nome local de um soquete (lida com endereços IPv6).

BOOL GetSockNameEx(
    CString& rSocketAddress,
    UINT& rSocketPort);

Parâmetros

rSocketAddress
Referência a um objeto CString que recebe um endereço IP separado por pontos.

rSocketPort
Referência a um UINT que armazena uma porta.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT O argumento lpSockAddrLen não é grande o suficiente.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAENOTSOCK O descritor não é um soquete.

• WSAEINVAL O soquete não foi associado a um endereço com Bind.

Comentários

Essa chamada é a mesma que CAsyncSocket::GetSockName, exceto que ela manipula endereços IPv6, bem como protocolos mais antigos.

Essa chamada é especialmente útil quando uma chamada Connect foi feita sem fazer uma chamada Bind primeiro; essa chamada fornece os únicos meios pelos quais você pode determinar a associação local que foi definida pelo sistema.

CAsyncSocket::GetSockOpt

Chame essa função de membro para recuperar uma opção de soquete.

BOOL GetSockOpt(
    int nOptionName,
    void* lpOptionValue,
    int* lpOptionLen,
    int nLevel = SOL_SOCKET);

Parâmetros

nOptionName
A opção de soquete para a qual o valor deve ser recuperado.

lpOptionValue
Um ponteiro para o buffer no qual o valor da opção solicitada deve ser retornado. O valor associado à opção selecionada é retornado no buffer lpOptionValue. O inteiro apontado por lpOptionLen deve conter originalmente o tamanho desse buffer em bytes; e, no retorno, ele será definido como o tamanho do valor retornado. Para SO_LINGER, esse será o tamanho de uma estrutura LINGER; para todas as outras opções, ele será do tamanho de um BOOL ou um int, dependendo da opção. Consulte a lista de opções e seus tamanhos na seção Comentários.

lpOptionLen
Um ponteiro para o tamanho do buffer lpOptionValue em bytes.

nLevel
O nível no qual a opção é definida; os únicos níveis com suporte são SOL_SOCKET e IPPROTO_TCP.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Se uma opção nunca tiver sido definida com SetSockOpt, GetSockOpt retorna o valor padrão para a opção. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT O argumento lpOptionLen era inválido.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAENOPROTOOPT A opção é desconhecida ou sem suporte. Em particular, não há suporte a SO_BROADCAST em soquetes do tipo SOCK_STREAM, enquantoSO_ACCEPTCONN, SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER e SO_OOBINLINE não têm suporte em soquetes do tipo SOCK_DGRAM.

• WSAENOTSOCK O descritor não é um soquete.

Comentários

GetSockOpt recupera o valor atual para uma opção de soquete associada a um soquete de qualquer tipo, em qualquer estado, e armazena o resultado em lpOptionValue. As opções afetam as operações de soquete, como o roteamento de pacotes, a transferência de dados fora da banda e assim por diante.

As seguintes opções são suportadas para GetSockOpt. O Type identifica o tipo de dados endereçados por lpOptionValue. A opção TCP_NODELAY usa nível IPPROTO_TCP; todas as outras opções usam o nível SOL_SOCKET.

As opções do Berkeley Software Distribution (BSD) para as quais não há suporte para GetSockOpt são:

Chamar GetSockOpt com uma opção sem suporte resultará em um código de erro de WSAENOPROTOOPT sendo retornado de GetLastError.

CAsyncSocket::IOCtl

Chame essa função de membro para controlar o modo de um soquete.

BOOL IOCtl(
    long lCommand,
    DWORD* lpArgument);

Parâmetros

lCommand
O comando a ser executado no soquete.

lpArgument
Um ponteiro para um parâmetro de lCommand.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEINVAL lCommand não é um comando válido ou lpArgument não é um parâmetro aceitável para lCommand, ou o comando não é aplicável ao tipo de soquete fornecido.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAENOTSOCK O descritor não é um soquete.

Comentários

Essa rotina pode ser usada em qualquer soquete em qualquer estado. Ele é usado para obter ou recuperar parâmetros operacionais associados ao soquete, independentemente do subsistema de protocolo e comunicações. Há suporte para os seguintes comandos:

• FIONBIO Habilitar ou desabilitar o modo de desbloqueio no soquete. O parâmetro lpArgument aponta para um DWORD, que não é zero se o modo de desbloqueio deve ser habilitado e zero se for para ser desabilitado. Se AsyncSelect tiver sido emitido em um soquete, qualquer tentativa de usar IOCtl para definir o soquete de volta ao modo de bloqueio falhará com WSAEINVAL. Para definir o soquete de volta para o modo de bloqueio e evitar o erro WSAEINVAL, um aplicativo deve primeiro desabilitar AsyncSelect chamando AsyncSelect com o parâmetro lEvent igual a 0 e, em seguida, chamar IOCtl.

• FIONREAD Determine o número máximo de bytes que podem ser lidos com uma chamada Receive desse soquete. O parâmetro lpArgument aponta para um DWORD em que IOCtl armazena o resultado. Se esse soquete for do tipo SOCK_STREAM, FIONREAD retornará a quantidade total de dados que podem ser lidos em um único Receive; normalmente é o mesmo que a quantidade total de dados enfileirados no soquete. Se esse soquete for do tipo SOCK_DGRAM, FIONREAD retornará o tamanho do primeiro datagrama enfileirado no soquete.

• SIOCATMARK Determine se todos os dados fora de banda foram lidos. Isso se aplica apenas a um soquete do tipo SOCK_STREAM que foi configurado para a recepção em linha de qualquer dado fora de banda (SO_OOBINLINE). Se nenhum dado fora de banda estiver esperando para ser lido, a operação retornará diferente de zero. Caso contrário, ele retorna 0 e o próximo Receive ou ReceiveFrom executado no soquete recuperará alguns ou todos os dados anteriores à "marca"; o aplicativo deve usar a operação SIOCATMARK para determinar se os dados permanecem. Se houver dados normais que precedem os dados "urgentes" (fora de banda), eles serão recebidos em ordem. (Observe que um Receive ou ReceiveFrom nunca misturará dados fora de banda e normais na mesma chamada.) O parâmetro lpArgument aponta para um DWORD em que IOCtl armazena o resultado.

Essa função é um subconjunto de ioctl() como usado em soquetes Berkeley. Em particular, não há nenhum comando que seja equivalente a FIOASYNC, embora SIOCATMARK seja o único comando no nível de soquete com suporte.

CAsyncSocket::Listen

Chame essa função de membro para escutar solicitações de conexão de entrada.

BOOL Listen(int nConnectionBacklog = 5);

Parâmetros

nConnectionBacklog
O comprimento máximo para o qual a fila de conexões pendentes pode aumentar. O intervalo válido é de 1 a 5.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEADDRINUSE Foi feita uma tentativa de escutar um endereço em uso.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAEINVAL O soquete não foi associado a Bind ou já está conectado.

• WSAEISCONN O soquete já está conectado.

• WSAEMFILE Nenhum outro descritor de arquivo disponível.

• WSAENOBUFS Nenhum espaço de buffer disponível.

• WSAENOTSOCK O descritor não é um soquete.

• WSAEOPNOTSUPP O soquete referenciado não é de um tipo que dá suporte à operação Listen.

Comentários

Para aceitar conexões, o soquete é criado primeiro com Create, um backlog para conexões de entrada é especificado com Listen e, em seguida, as conexões são aceitas com Accept. Listen aplica-se somente a soquetes que dão suporte a conexões, ou seja, aquelas do tipo SOCK_STREAM. Esse soquete é colocado no modo "passivo", em que as conexões de entrada são reconhecidas e enfileiradas até a aceitação pelo processo.

Essa função normalmente é usada por servidores (ou qualquer aplicativo que queira aceitar conexões) que possa ter mais de uma solicitação de conexão por vez: se uma solicitação de conexão chegar com a fila cheia, o cliente receberá um erro com uma indicação de WSAECONNREFUSED.

Listen tenta continuar a funcionar racionalmente quando não há portas disponíveis (descritores). Ele aceitará conexões até que a fila seja esvaziada. Se as portas ficarem disponíveis, uma chamada posterior para Listen ou Accept recarregará a fila para o "backlog" atual ou mais recente, se possível, e retomará a escuta de conexões de entrada.

CAsyncSocket::m_hSocket

Contém o identificador SOCKET do soquete encapsulado por esse objeto CAsyncSocket.

SOCKET m_hSocket;

CAsyncSocket::OnAccept

Chamado pela estrutura para notificar um soquete de escuta de que ele pode aceitar solicitações de conexão pendentes chamando a Accept função de membro.

virtual void OnAccept(int nErrorCode);

Parâmetros

nErrorCode
O erro mais recente em um soquete. Os seguintes códigos de erro se aplicam à função de membro OnAccept:

• 0 A função executada com êxito.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

Comentários

Para obter mais informações, consulte Windows Sockets: notificações de soquete.

CAsyncSocket::OnClose

Chamado pela estrutura para notificar esse soquete de que o soquete conectado está fechado por seu processo.

virtual void OnClose(int nErrorCode);

Parâmetros

nErrorCode
O erro mais recente em um soquete. Os seguintes códigos de erro se aplicam à função de membro OnClose:

• 0 A função executada com êxito.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAECONNRESET A conexão foi redefinida pelo lado remoto.

• WSAECONNABORTED A conexão foi anulada devido ao tempo limite ou outra falha.

Comentários

Para obter mais informações, consulte Windows Sockets: notificações de soquete.

CAsyncSocket::OnConnect

Chamado pela estrutura para notificar esse soquete de conexão de que sua tentativa de conexão foi concluída, seja com êxito ou em erro.

virtual void OnConnect(int nErrorCode);

Parâmetros

nErrorCode
O erro mais recente em um soquete. Os seguintes códigos de erro se aplicam à função de membro OnConnect:

• 0 A função executada com êxito.

• WSAEADDRINUSE O endereço especificado já está sendo usado.

• WSAEADDRNOTAVAIL O endereço especificado não está disponível no computador local.

• WSAEAFNOSUPPORT Os endereços na família especificada não podem ser usados com este soquete.

• WSAECONNREFUSED A tentativa de conexão foi rejeitada de modo forçado.

• WSAEDESTADDRREQ Endereço de destino necessário.

• WSAEFAULT O argumento lpSockAddrLen está incorreto.

• WSAEINVAL O soquete já está associado a um endereço.

• WSAEISCONN O soquete já está conectado.

• WSAEMFILE Nenhum outro descritor de arquivo disponível.

• WSAENETUNREACH A rede não pode ser alcançada através desse host neste momento.

• WSAENOBUFS Nenhum espaço de buffer disponível. O soquete não pode ser conectado.

• WSAENOTCONN O soquete não está conectado.

• WSAENOTSOCK O descritor é um arquivo, não um soquete.

• WSAETIMEDOUT A tentativa de se conectar com o tempo limite sem estabelecer uma conexão.

Comentários

Para obter mais informações, consulte Windows Sockets: notificações de soquete.

Exemplo

void CMyAsyncSocket::OnConnect(int nErrorCode) // CMyAsyncSocket is
                                               // derived from CAsyncSocket
{
   if (0 != nErrorCode)
   {
      switch (nErrorCode)
      {
      case WSAEADDRINUSE:
         AfxMessageBox(_T("The specified address is already in use.\n"));
         break;
      case WSAEADDRNOTAVAIL:
         AfxMessageBox(_T("The specified address is not available from ")
                       _T("the local machine.\n"));
         break;
      case WSAEAFNOSUPPORT:
         AfxMessageBox(_T("Addresses in the specified family cannot be ")
                       _T("used with this socket.\n"));
         break;
      case WSAECONNREFUSED:
         AfxMessageBox(_T("The attempt to connect was forcefully rejected.\n"));
         break;
      case WSAEDESTADDRREQ:
         AfxMessageBox(_T("A destination address is required.\n"));
         break;
      case WSAEFAULT:
         AfxMessageBox(_T("The lpSockAddrLen argument is incorrect.\n"));
         break;
      case WSAEINVAL:
         AfxMessageBox(_T("The socket is already bound to an address.\n"));
         break;
      case WSAEISCONN:
         AfxMessageBox(_T("The socket is already connected.\n"));
         break;
      case WSAEMFILE:
         AfxMessageBox(_T("No more file descriptors are available.\n"));
         break;
      case WSAENETUNREACH:
         AfxMessageBox(_T("The network cannot be reached from this host ")
                       _T("at this time.\n"));
         break;
      case WSAENOBUFS:
         AfxMessageBox(_T("No buffer space is available. The socket ")
                       _T("cannot be connected.\n"));
         break;
      case WSAENOTCONN:
         AfxMessageBox(_T("The socket is not connected.\n"));
         break;
      case WSAENOTSOCK:
         AfxMessageBox(_T("The descriptor is a file, not a socket.\n"));
         break;
      case WSAETIMEDOUT:
         AfxMessageBox(_T("The attempt to connect timed out without ")
                       _T("establishing a connection. \n"));
         break;
      default:
         TCHAR szError[256];
         _stprintf_s(szError, _T("OnConnect error: %d"), nErrorCode);
         AfxMessageBox(szError);
         break;
      }
      AfxMessageBox(_T("Please close the application"));
   }
   CAsyncSocket::OnConnect(nErrorCode);
}

CAsyncSocket::OnOutOfBandData

Chamado pela estrutura para notificar o soquete de recebimento que o soquete de envio tem dados fora de banda a serem enviados.

virtual void OnOutOfBandData(int nErrorCode);

Parâmetros

nErrorCode
O erro mais recente em um soquete. Os seguintes códigos de erro se aplicam à função de membro OnOutOfBandData:

• 0 A função executada com êxito.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

Comentários

Os dados fora de banda são um canal logicamente independente associado a cada par de soquetes conectados do tipo SOCK_STREAM. O canal geralmente é usado para enviar dados urgentes.

O MFC dá suporte a dados fora de banda, mas os usuários de classe CAsyncSocket são desencorajados a usá-los. A maneira mais fácil é criar um segundo soquete para passar esses dados. Para obter mais informações sobre dados fora de banda, consulte Windows Sockets: notificações de soquete.

CAsyncSocket::OnReceive

Chamado pela estrutura para notificar esse soquete de que há dados no buffer que podem ser recuperados chamando a função de membro Receive.

virtual void OnReceive(int nErrorCode);

Parâmetros

nErrorCode
O erro mais recente em um soquete. Os seguintes códigos de erro se aplicam à função de membro OnReceive:

• 0 A função executada com êxito.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

Comentários

Para obter mais informações, consulte Windows Sockets: notificações de soquete.

Exemplo

void CMyAsyncSocket::OnReceive(int nErrorCode) // CMyAsyncSocket is
                                               // derived from CAsyncSocket
{
  static int i = 0;

  i++;

  TCHAR buff[4096];
  int nRead;
  nRead = Receive(buff, 4096);

  switch (nRead)
  {
  case 0:
    Close();
    break;
  case SOCKET_ERROR:
    if (GetLastError() != WSAEWOULDBLOCK)
    {
      AfxMessageBox(_T("Error occurred"));
      Close();
    }
    break;
  default:
    buff[nRead] = _T('\0'); //terminate the string
    CString szTemp(buff);
    m_strRecv += szTemp; // m_strRecv is a CString declared
                         // in CMyAsyncSocket
    if (szTemp.CompareNoCase(_T("bye")) == 0)
    {
      ShutDown();
      s_eventDone.SetEvent();
    }
  }
  CAsyncSocket::OnReceive(nErrorCode);
}

CAsyncSocket::OnSend

Chamado pela estrutura para notificar o soquete de que agora ele pode enviar dados chamando a função de membro Send.

virtual void OnSend(int nErrorCode);

Parâmetros

nErrorCode
O erro mais recente em um soquete. Os seguintes códigos de erro se aplicam à função de membro OnSend:

• 0 A função executada com êxito.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

Comentários

Para obter mais informações, consulte Windows Sockets: notificações de soquete.

Exemplo

// CMyAsyncSocket is derived from CAsyncSocket and defines the
// following variables:
//    CString  m_sendBuffer;   //for async send
//    int      m_nBytesSent;
//    int      m_nBytesBufferSize;
void CMyAsyncSocket::OnSend(int nErrorCode)
{
   while (m_nBytesSent < m_nBytesBufferSize)
   {
      int dwBytes;

      if ((dwBytes = Send((LPCTSTR)m_sendBuffer + m_nBytesSent,
                          m_nBytesBufferSize - m_nBytesSent)) == SOCKET_ERROR)
      {
         if (GetLastError() == WSAEWOULDBLOCK)
         {
            break;
         }
         else
         {
            TCHAR szError[256];
            _stprintf_s(szError, _T("Server Socket failed to send: %d"),
                        GetLastError());
            Close();
            AfxMessageBox(szError);
         }
      }
      else
      {
         m_nBytesSent += dwBytes;
      }
   }

   if (m_nBytesSent == m_nBytesBufferSize)
   {
      m_nBytesSent = m_nBytesBufferSize = 0;
      m_sendBuffer = _T("");
   }

   CAsyncSocket::OnSend(nErrorCode);
}

CAsyncSocket::operator =

Atribui um novo valor a um objeto CAsyncSocket.

void operator=(const CAsyncSocket& rSrc);

Parâmetros

rSrc
Uma referência a um objeto CAsyncSocket existente.

Comentários

Chame essa função para copiar um objeto existente CAsyncSocket para outro objeto CAsyncSocket.

CAsyncSocket::operator SOCKET

Use esse operador para recuperar o identificador SOCKET do objeto CAsyncSocket.

operator SOCKET() const;

Valor de retorno

Se tiver êxito, o identificador do objeto SOCKET; caso contrário, NULL.

Comentários

Você pode usar o identificador para chamar as APIs do Windows diretamente.

CAsyncSocket::Receive

Chame essa função de membro para receber dados de um soquete.

virtual int Receive(
    void* lpBuf,
    int nBufLen,
    int nFlags = 0);

Parâmetros

lpBuf
Um buffer para os dados de entrada.

nBufLen
O tamanho de lpBuf em bytes.

nFlags
Especifica a maneira como a chamada é feita. A semântica dessa função é determinada pelas opções de soquete e pelo parâmetro nFlags. Este último é construído combinando qualquer um dos seguintes valores com o operador OR bit a bit C++ (|):

• MSG_PEEK Inspeção dos dados de entrada. Os dados são copiados para o buffer, mas não são removidos da fila de entrada.

• MSG_OOB Processar dados fora de banda.

Valor de retorno

Se nenhum erro ocorrer, Receive retornará o número de bytes recebidos. Se a conexão tiver sido fechada, ela retornará 0. Caso contrário, um valor SOCKET_ERROR é retornado e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAENOTCONN O soquete não está conectado.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAENOTSOCK O descritor não é um soquete.

• WSAEOPNOTSUPP MSG_OOB foi especificado, mas o soquete não é do tipo SOCK_STREAM.

• WSAESHUTDOWN O soquete foi desligado; não é possível chamar Receive em um soquete depois de ShutDown ter sido invocado com nHow definido como 0 ou 2.

• WSAEWOULDBLOCK O soquete é marcado como não desbloqueio e a operação Receive seria bloqueada.

• WSAEMSGSIZE O datagrama era muito grande para caber no buffer especificado e foi truncado.

• WSAEINVAL O soquete não foi associado a Bind.

• WSAECONNABORTED O circuito virtual foi anulado devido ao tempo limite ou outra falha.

• WSAECONNRESET O circuito virtual foi redefinido pelo lado remoto.

Comentários

Essa função é usada para soquetes de fluxo ou datagrama conectados e é usada para ler dados de entrada.

Para soquetes do tipo SOCK_STREAM, a quantidade de informações que está disponível atualmente até o tamanho do buffer fornecido é retornada. Se o soquete tiver sido configurado para recepção em linha de dados fora de banda (opção de soquete SO_OOBINLINE) e os dados fora de banda não forem lidos, somente dados fora de banda serão retornados. O aplicativo pode usar a opção IOCtlSIOCATMARK ou OnOutOfBandData para determinar se ainda há mais dados fora de banda a serem lidos.

Para soquetes de datagram, os dados são extraídos do primeiro datagrama enfileirado, até o tamanho do buffer fornecido. Se o datagram for maior que o buffer fornecido, o buffer será preenchido com a primeira parte do datagrama, o excesso de dados será perdido e Receive retornará um valor de SOCKET_ERROR com código de erro definido como WSAEMSGSIZE. Se nenhum dado de entrada estiver disponível no soquete, um valor será retornado com o código de erro SOCKET_ERROR definido como WSAEWOULDBLOCK. A função de retorno de chamada OnReceive pode ser usada para determinar quando mais dados chegam.

Se o soquete for do tipo SOCK_STREAM e o lado remoto tiver desligado a conexão normalmente, um Receive concluirá imediatamente com 0 bytes recebidos. Se a conexão tiver sido redefinida, um Receive com o erro WSAECONNRESET.

Receive deve ser chamado apenas uma vez para cada vez que CAsyncSocket::OnReceive for chamado.

Exemplo

Confira o exemplo de CAsyncSocket::OnReceive.

CAsyncSocket::ReceiveFrom

Chame essa função de membro para receber um datagrama e armazenar o endereço de origem na estrutura SOCKADDR ou em rSocketAddress.

int ReceiveFrom(
    void* lpBuf,
    int nBufLen,
    CString& rSocketAddress,
    UINT& rSocketPort,
    int nFlags = 0);

int ReceiveFrom(
    void* lpBuf,
    int nBufLen,
    SOCKADDR* lpSockAddr,
    int* lpSockAddrLen,
    int nFlags = 0);

Parâmetros

lpBuf
Um buffer para os dados de entrada.

nBufLen
O tamanho de lpBuf em bytes.

rSocketAddress
Referência a um objeto CString que recebe um endereço IP separado por pontos.

rSocketPort
Referência a um UINT que armazena uma porta.

lpSockAddr
Um ponteiro para uma estrutura SOCKADDR que contém o endereço de origem no retorno.

lpSockAddrLen
Um ponteiro para o comprimento do endereço de origem em lpSockAddr, em bytes.

nFlags
Especifica a maneira como a chamada é feita. A semântica dessa função é determinada pelas opções de soquete e pelo parâmetro nFlags. Este último é construído combinando qualquer um dos seguintes valores com o operador OR bit a bit C++ (|):

• MSG_PEEK Inspeção dos dados de entrada. Os dados são copiados para o buffer, mas não são removidos da fila de entrada.

• MSG_OOB Processar dados fora de banda.

Valor de retorno

Se nenhum erro ocorrer, ReceiveFrom retornará o número de bytes recebidos. Se a conexão tiver sido fechada, ela retornará 0. Caso contrário, um valor SOCKET_ERROR é retornado e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT O argumento lpSockAddrLen era inválido: o buffer lpSockAddr era muito pequeno para acomodar o endereço par.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAEINVAL O soquete não foi associado a Bind.

• WSAENOTCONN O soquete não está conectado (somente SOCK_STREAM).

• WSAENOTSOCK O descritor não é um soquete.

• WSAEOPNOTSUPP MSG_OOB foi especificado, mas o soquete não é do tipo SOCK_STREAM.

• WSAESHUTDOWN O soquete foi desligado; não é possível chamar ReceiveFrom em um soquete depois de ShutDown ter sido invocado com nHow definido como 0 ou 2.

• WSAEWOULDBLOCK O soquete é marcado como não desbloqueio e a operação ReceiveFrom seria bloqueada.

• WSAEMSGSIZE O datagrama era muito grande para caber no buffer especificado e foi truncado.

• WSAECONNABORTED O circuito virtual foi anulado devido ao tempo limite ou outra falha.

• WSAECONNRESET O circuito virtual foi redefinido pelo lado remoto.

Comentários

Essa função é usada para ler dados de entrada em um soquete (possivelmente conectado) e capturar o endereço do qual os dados foram enviados.

Para lidar com endereços IPv6, use CAsyncSocket::ReceiveFromEx.

Para soquetes do tipo SOCK_STREAM, a quantidade de informações que está disponível atualmente até o tamanho do buffer fornecido é retornada. Se o soquete tiver sido configurado para recepção em linha de dados fora de banda (opção de soquete SO_OOBINLINE) e os dados fora de banda não forem lidos, somente dados fora de banda serão retornados. O aplicativo pode usar a opção IOCtlSIOCATMARK ou OnOutOfBandData para determinar se ainda há mais dados fora de banda a serem lidos. Os parâmetros lpSockAddr e lpSockAddrLen são ignorados para soquetes SOCK_STREAM.

Para soquetes de datagram, os dados são extraídos do primeiro datagrama enfileirado, até o tamanho do buffer fornecido. Se o datagram for maior que o buffer fornecido, o buffer será preenchido com a primeira parte da mensagem, o excesso de dados será perdido e ReceiveFrom retornará um valor de SOCKET_ERROR com código de erro definido como WSAEMSGSIZE.

Se lpSockAddr for diferente de zero e o soquete for do tipo SOCK_DGRAM, o endereço de rede do soquete que enviou os dados será copiado para a estrutura SOCKADDR correspondente. O valor apontado por lpSockAddrLen é inicializado para o tamanho dessa estrutura e é modificado no retorno para indicar o tamanho real do endereço armazenado lá. Se nenhum dado de entrada estiver disponível no soquete, a chamada ReceiveFrom aguardará a chegada dos dados, a menos que o soquete não esteja desbloqueado. Nesse caso, um valor é retornado com o código de erro SOCKET_ERROR definido como WSAEWOULDBLOCK. A chamada de retorno OnReceive pode ser usada para determinar quando mais dados chegam.

Se o soquete for do tipo SOCK_STREAM e o lado remoto tiver desligado a conexão normalmente, um ReceiveFrom concluirá imediatamente com 0 bytes recebidos.

CAsyncSocket::ReceiveFromEx

Chame essa função de membro para receber um datagrama e armazenar o endereço de origem na estrutura SOCKADDR ou em rSocketAddress (lida com endereços IPv6).

int ReceiveFromEx(
    void* lpBuf,
    int nBufLen,
    CString& rSocketAddress,
    UINT& rSocketPort,
    int nFlags = 0);

Parâmetros

lpBuf
Um buffer para os dados de entrada.

nBufLen
O tamanho de lpBuf em bytes.

rSocketAddress
Referência a um objeto CString que recebe um endereço IP separado por pontos.

rSocketPort
Referência a um UINT que armazena uma porta.

nFlags
Especifica a maneira como a chamada é feita. A semântica dessa função é determinada pelas opções de soquete e pelo parâmetro nFlags. Este último é construído combinando qualquer um dos seguintes valores com o operador OR bit a bit C++ (|):

• MSG_PEEK Inspeção dos dados de entrada. Os dados são copiados para o buffer, mas não são removidos da fila de entrada.

• MSG_OOB Processar dados fora de banda.

Valor de retorno

Se nenhum erro ocorrer, ReceiveFromEx retornará o número de bytes recebidos. Se a conexão tiver sido fechada, ela retornará 0. Caso contrário, um valor SOCKET_ERROR é retornado e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT O argumento lpSockAddrLen era inválido: o buffer lpSockAddr era muito pequeno para acomodar o endereço par.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAEINVAL O soquete não foi associado a Bind.

• WSAENOTCONN O soquete não está conectado (somente SOCK_STREAM).

• WSAENOTSOCK O descritor não é um soquete.

• WSAEOPNOTSUPP MSG_OOB foi especificado, mas o soquete não é do tipo SOCK_STREAM.

• WSAESHUTDOWN O soquete foi desligado; não é possível chamar ReceiveFromEx em um soquete depois de ShutDown ter sido invocado com nHow definido como 0 ou 2.

• WSAEWOULDBLOCK O soquete é marcado como não desbloqueio e a operação ReceiveFromEx seria bloqueada.

• WSAEMSGSIZE O datagrama era muito grande para caber no buffer especificado e foi truncado.

• WSAECONNABORTED O circuito virtual foi anulado devido ao tempo limite ou outra falha.

• WSAECONNRESET O circuito virtual foi redefinido pelo lado remoto.

Comentários

Essa função é usada para ler dados de entrada em um soquete (possivelmente conectado) e capturar o endereço do qual os dados foram enviados.

Essa função é a mesma que CAsyncSocket::ReceiveFrom, exceto que ela manipula endereços IPv6, bem como protocolos mais antigos.

Para soquetes do tipo SOCK_STREAM, a quantidade de informações que está disponível atualmente até o tamanho do buffer fornecido é retornada. Se o soquete tiver sido configurado para recepção em linha de dados fora de banda (opção de soquete SO_OOBINLINE) e os dados fora de banda não forem lidos, somente dados fora de banda serão retornados. O aplicativo pode usar a opção IOCtlSIOCATMARK ou OnOutOfBandData para determinar se ainda há mais dados fora de banda a serem lidos. Os parâmetros lpSockAddr e lpSockAddrLen são ignorados para soquetes SOCK_STREAM.

Para soquetes de datagram, os dados são extraídos do primeiro datagrama enfileirado, até o tamanho do buffer fornecido. Se o datagram for maior que o buffer fornecido, o buffer será preenchido com a primeira parte da mensagem, o excesso de dados será perdido e ReceiveFromEx retornará um valor de SOCKET_ERROR com código de erro definido como WSAEMSGSIZE.

Se lpSockAddr for diferente de zero e o soquete for do tipo SOCK_DGRAM, o endereço de rede do soquete que enviou os dados será copiado para a estrutura SOCKADDR correspondente. O valor apontado por lpSockAddrLen é inicializado para o tamanho dessa estrutura e é modificado no retorno para indicar o tamanho real do endereço armazenado lá. Se nenhum dado de entrada estiver disponível no soquete, a chamada ReceiveFromEx aguardará a chegada dos dados, a menos que o soquete não esteja desbloqueado. Nesse caso, um valor é retornado com o código de erro SOCKET_ERROR definido como WSAEWOULDBLOCK. A chamada de retorno OnReceive pode ser usada para determinar quando mais dados chegam.

Se o soquete for do tipo SOCK_STREAM e o lado remoto tiver desligado a conexão normalmente, um ReceiveFromEx concluirá imediatamente com 0 bytes recebidos.

CAsyncSocket::Send

Chame essa função de membro para enviar dados em um soquete conectado.

virtual int Send(
    const void* lpBuf,
    int nBufLen,
    int nFlags = 0);

Parâmetros

lpBuf
Um buffer que contém os dados a serem transmitidos.

nBufLen
O tamanho dos dados lpBuf, em bytes.

nFlags
Especifica a maneira como a chamada é feita. A semântica dessa função é determinada pelas opções de soquete e pelo parâmetro nFlags. Este último é construído combinando qualquer um dos seguintes valores com o operador OR bit a bit C++ (|):

• MSG_DONTROUTE Especifica que os dados não devem estar sujeitos ao roteamento. Um fornecedor do Windows Sockets pode optar por ignorar esse sinalizador.

• MSG_OOB Enviar dados fora da banda (somente SOCK_STREAM).

Valor de retorno

Se nenhum erro ocorrer, Send retornará o número total de caracteres enviados. (Observe que isso pode ser menor do que o número indicado por nBufLen.) Caso contrário, um valor é retornado e um código de erro SOCKET_ERROR específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEACCES O endereço solicitado é um endereço de transmissão, mas o sinalizador apropriado não foi definido.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAEFAULT O argumento lpBuf não está em uma parte válida do espaço de endereço do usuário.

• WSAENETRESET A conexão deve ser redefinida porque a implementação dos Soquetes do Windows a retirou.

• WSAENOBUFS A implementação do Windows Sockets relata um deadlock de buffer.

• WSAENOTCONN O soquete não está conectado.

• WSAENOTSOCK O descritor não é um soquete.

• WSAEOPNOTSUPP MSG_OOB foi especificado, mas o soquete não é do tipo SOCK_STREAM.

• WSAESHUTDOWN O soquete foi desligado; não é possível chamar Send em um soquete depois de ShutDown ter sido invocado com nHow definido como 1 ou 2.

• WSAEWOULDBLOCK O soquete é marcado como não desbloqueio e a operação solicitada seria bloqueada.

• WSAEMSGSIZE O soquete é do tipo SOCK_DGRAM, e o datagrama é maior do que o máximo suportado pela implementação do Windows Sockets.

• WSAEINVAL O soquete não foi associado a Bind.

• WSAECONNABORTED O circuito virtual foi anulado devido ao tempo limite ou outra falha.

• WSAECONNRESET O circuito virtual foi redefinido pelo lado remoto.

Comentários

Send é usado para gravar dados de saída em soquetes de fluxo ou datagrama conectados. Para soquetes de datagrama, deve-se tomar cuidado para não exceder o tamanho máximo do pacote IP das sub-redes subjacentes, que é fornecido pelo elemento iMaxUdpDg na estrutura WSADATA retornada por AfxSocketInit. Se os dados forem muito longos para passar atomicamente pelo protocolo subjacente, o erro WSAEMSGSIZE será retornado por meio GetLastError e nenhum dado será transmitido.

Observe que, para um soquete de datagrama, a conclusão bem-sucedida de um Send não indica que os dados foram entregues com êxito.

Em objetos CAsyncSocket de tipo SOCK_STREAM, o número de bytes gravados pode ser entre 1 e o comprimento solicitado, dependendo da disponibilidade do buffer nos hosts locais e estrangeiros.

Exemplo

Confira o exemplo de CAsyncSocket::OnSend.

CAsyncSocket::SendTo

Chame essa função de membro para enviar dados para um destino específico.

int SendTo(
    const void* lpBuf,
    int nBufLen,
    UINT nHostPort,
    LPCTSTR lpszHostAddress = NULL,
    int nFlags = 0);

int SendTo(
    const void* lpBuf,
    int nBufLen,
    const SOCKADDR* lpSockAddr,
    int nSockAddrLen,
    int nFlags = 0);

Parâmetros

lpBuf
Um buffer que contém os dados a serem transmitidos.

nBufLen
O tamanho dos dados lpBuf, em bytes.

nHostPort
A porta que identifica o aplicativo de soquete.

lpszHostAddress
O endereço de rede do soquete ao qual esse objeto está conectado: um nome de computador como "ftp.microsoft.com" ou um número separado por pontos, como "128.56.22.8".

nFlags
Especifica a maneira como a chamada é feita. A semântica dessa função é determinada pelas opções de soquete e pelo parâmetro nFlags. Este último é construído combinando qualquer um dos seguintes valores com o operador OR bit a bit C++ (|):

• MSG_DONTROUTE Especifica que os dados não devem estar sujeitos ao roteamento. Um fornecedor do Windows Sockets pode optar por ignorar esse sinalizador.

• MSG_OOB Enviar dados fora da banda (somente SOCK_STREAM).

lpSockAddr
Um ponteiro para uma estrutura SOCKADDR que contém o endereço do soquete de destino.

nSockAddrLen
O comprimento do endereço em lpSockAddr, em bytes.

Valor de retorno

Se nenhum erro ocorrer, SendTo retornará o número total de caracteres enviados. (Observe que isso pode ser menor do que o número indicado por nBufLen.) Caso contrário, um valor é retornado e um código de erro SOCKET_ERROR específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEACCES O endereço solicitado é um endereço de transmissão, mas o sinalizador apropriado não foi definido.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAEFAULT Os parâmetros lpBuf ou lpSockAddr não fazem parte do espaço de endereço do usuário ou o argumento lpSockAddr é muito pequeno (menor que o tamanho de uma estrutura SOCKADDR).

• WSAEINVAL O nome de host é inválido.

• WSAENETRESET A conexão deve ser redefinida porque a implementação dos Soquetes do Windows a retirou.

• WSAENOBUFS A implementação do Windows Sockets relata um deadlock de buffer.

• WSAENOTCONN O soquete não está conectado (somente SOCK_STREAM).

• WSAENOTSOCK O descritor não é um soquete.

• WSAEOPNOTSUPP MSG_OOB foi especificado, mas o soquete não é do tipo SOCK_STREAM.

• WSAESHUTDOWN O soquete foi desligado; não é possível chamar SendTo em um soquete depois de ShutDown ter sido invocado com nHow definido como 1 ou 2.

• WSAEWOULDBLOCK O soquete é marcado como não desbloqueio e a operação solicitada seria bloqueada.

• WSAEMSGSIZE O soquete é do tipo SOCK_DGRAM, e o datagrama é maior do que o máximo suportado pela implementação do Windows Sockets.

• WSAECONNABORTED O circuito virtual foi anulado devido ao tempo limite ou outra falha.

• WSAECONNRESET O circuito virtual foi redefinido pelo lado remoto.

• WSAEADDRNOTAVAIL O endereço especificado não está disponível no computador local.

• WSAEAFNOSUPPORT Os endereços na família especificada não podem ser usados com este soquete.

• WSAEDESTADDRREQ Endereço de destino necessário.

• WSAENETUNREACH A rede não pode ser alcançada através desse host neste momento.

Comentários

SendTo é usado em soquetes de fluxo ou datagrama e é usado para gravar dados de saída em um soquete. Para soquetes de datagrama, deve-se tomar cuidado para não exceder o tamanho máximo do pacote IP das sub-redes subjacentes, que é fornecido pelo elemento iMaxUdpDg na estrutura WSADATA preenchida por AfxSocketInit. Se os dados forem muito longos para passar atomicamente pelo protocolo subjacente, o erro WSAEMSGSIZE será retornado, e nenhum dado será transmitido.

Observe que a conclusão bem-sucedida de um SendTo não indica que os dados foram entregues com êxito.

SendTo é usado apenas em um soquete SOCK_DGRAM para enviar um datagrama para um soquete específico identificado pelo parâmetro lpSockAddr.

Para enviar uma transmissão (somente em um SOCK_DGRAM), o endereço no parâmetro lpSockAddr deve ser construído usando o endereço IP especial INADDR_BROADCAST (definido no arquivo de cabeçalho WINSOCK.H do Windows Socket) junto com o número de porta pretendido. Ou, se o parâmetro lpszHostAddress for NULL, o soquete será configurado para transmissão. Geralmente, não é recomendável que um datagrama de difusão exceda o tamanho em que a fragmentação pode ocorrer, o que implica que a parte de dados do datagram (excluindo cabeçalhos) não deve exceder 512 bytes.

Para lidar com endereços IPv6, use CAsyncSocket::SendToEx.

CAsyncSocket::SendToEx

Chame essa função de membro para enviar dados para um destino específico (lida com endereços IPv6).

int SendToEx(
    const void* lpBuf,
    int nBufLen,
    UINT nHostPort,
    LPCTSTR lpszHostAddress = NULL,
    int nFlags = 0);

Parâmetros

lpBuf
Um buffer que contém os dados a serem transmitidos.

nBufLen
O tamanho dos dados lpBuf, em bytes.

nHostPort
A porta que identifica o aplicativo de soquete.

lpszHostAddress
O endereço de rede do soquete ao qual esse objeto está conectado: um nome de computador como "ftp.microsoft.com" ou um número separado por pontos, como "128.56.22.8".

nFlags
Especifica a maneira como a chamada é feita. A semântica dessa função é determinada pelas opções de soquete e pelo parâmetro nFlags. Este último é construído combinando qualquer um dos seguintes valores com o operador OR bit a bit C++ (|):

• MSG_DONTROUTE Especifica que os dados não devem estar sujeitos ao roteamento. Um fornecedor do Windows Sockets pode optar por ignorar esse sinalizador.

• MSG_OOB Enviar dados fora da banda (somente SOCK_STREAM).

Valor de retorno

Se nenhum erro ocorrer, SendToEx retornará o número total de caracteres enviados. (Observe que isso pode ser menor do que o número indicado por nBufLen.) Caso contrário, um valor é retornado e um código de erro SOCKET_ERROR específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEACCES O endereço solicitado é um endereço de transmissão, mas o sinalizador apropriado não foi definido.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAEFAULT Os parâmetros lpBuf ou lpSockAddr não fazem parte do espaço de endereço do usuário ou o argumento lpSockAddr é muito pequeno (menor que o tamanho de uma estrutura SOCKADDR).

• WSAEINVAL O nome de host é inválido.

• WSAENETRESET A conexão deve ser redefinida porque a implementação dos Soquetes do Windows a retirou.

• WSAENOBUFS A implementação do Windows Sockets relata um deadlock de buffer.

• WSAENOTCONN O soquete não está conectado (somente SOCK_STREAM).

• WSAENOTSOCK O descritor não é um soquete.

• WSAEOPNOTSUPP MSG_OOB foi especificado, mas o soquete não é do tipo SOCK_STREAM.

• WSAESHUTDOWN O soquete foi desligado; não é possível chamar SendToEx em um soquete depois de ShutDown ter sido invocado com nHow definido como 1 ou 2.

• WSAEWOULDBLOCK O soquete é marcado como não desbloqueio e a operação solicitada seria bloqueada.

• WSAEMSGSIZE O soquete é do tipo SOCK_DGRAM, e o datagrama é maior do que o máximo suportado pela implementação do Windows Sockets.

• WSAECONNABORTED O circuito virtual foi anulado devido ao tempo limite ou outra falha.

• WSAECONNRESET O circuito virtual foi redefinido pelo lado remoto.

• WSAEADDRNOTAVAIL O endereço especificado não está disponível no computador local.

• WSAEAFNOSUPPORT Os endereços na família especificada não podem ser usados com este soquete.

• WSAEDESTADDRREQ Endereço de destino necessário.

• WSAENETUNREACH A rede não pode ser alcançada através desse host neste momento.

Comentários

Esse método é o mesma que CAsyncSocket::SendTo, exceto que ele manipula endereços IPv6, bem como protocolos mais antigos.

SendToEx é usado em soquetes de fluxo ou datagrama e é usado para gravar dados de saída em um soquete. Para soquetes de datagrama, deve-se tomar cuidado para não exceder o tamanho máximo do pacote IP das sub-redes subjacentes, que é fornecido pelo elemento iMaxUdpDg na estrutura WSADATA preenchida por AfxSocketInit. Se os dados forem muito longos para passar atomicamente pelo protocolo subjacente, o erro WSAEMSGSIZE será retornado, e nenhum dado será transmitido.

Observe que a conclusão bem-sucedida de um SendToEx não indica que os dados foram entregues com êxito.

SendToEx é usado apenas em um soquete SOCK_DGRAM para enviar um datagrama para um soquete específico identificado pelo parâmetro lpSockAddr.

Para enviar uma transmissão (somente em um SOCK_DGRAM), o endereço no parâmetro lpSockAddr deve ser construído usando o endereço IP especial INADDR_BROADCAST (definido no arquivo de cabeçalho WINSOCK.H do Windows Socket) junto com o número de porta pretendido. Ou, se o parâmetro lpszHostAddress for NULL, o soquete será configurado para transmissão. Geralmente, não é recomendável que um datagrama de difusão exceda o tamanho em que a fragmentação pode ocorrer, o que implica que a parte de dados do datagram (excluindo cabeçalhos) não deve exceder 512 bytes.

CAsyncSocket::SetSockOpt

Chame essa função de membro para definir uma opção de soquete.

BOOL SetSockOpt(
    int nOptionName,
    const void* lpOptionValue,
    int nOptionLen,
    int nLevel = SOL_SOCKET);

Parâmetros

nOptionName
A opção de soquete para a qual o valor deve ser definido.

lpOptionValue
Um ponteiro para o buffer no qual o valor da opção solicitada é fornecido.

nOptionLen
O tamanho do buffer lpOptionValue em bytes.

nLevel
O nível no qual a opção é definida; os únicos níveis com suporte são SOL_SOCKET e IPPROTO_TCP.

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEFAULT lpOptionValue não está em uma parte válida do espaço de endereço do processo.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAEINVAL nLevel não é válida ou as informações contidas não lpOptionValue são válidas.

• WSAENETRESET A conexão atingiu o tempo limite quando SO_KEEPALIVE é definido.

• WSAENOPROTOOPT A opção é desconhecida ou sem suporte. Em particular, SO_BROADCAST não é suportado em soquetes de tipo SOCK_STREAM, enquanto SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER e SO_OOBINLINE não são suportados em soquetes de tipo SOCK_DGRAM.

• WSAENOTCONN A conexão foi redefinida quando SO_KEEPALIVE é definido.

• WSAENOTSOCK O descritor não é um soquete.

Comentários

SetSockOpt define o valor atual para uma opção de soquete associada a um soquete de qualquer tipo, em qualquer estado. Embora as opções possam existir em vários níveis de protocolo, essa especificação define apenas as opções que existem no nível superior de "soquete". As opções afetam as operações de soquete, como se os dados acelerados são recebidos no fluxo de dados normal, se as mensagens de transmissão podem ser enviadas no soquete e assim por diante.

Há dois tipos de opções de soquete: opções boolianas que habilitam ou desabilitam um recurso ou comportamento e opções que exigem um valor inteiro ou uma estrutura. Para habilitar uma opção booliana, lpOptionValue aponta para um inteiro diferente de zero. Para desabilitar a opção, lpOptionValue aponta para um inteiro igual a zero. nOptionLen deve ser igual a sizeof(BOOL) para opções boolianas. Para outras opções, lpOptionValue aponta para o inteiro ou estrutura que contém o valor desejado para a opção e nOptionLen é o tamanho do inteiro ou da estrutura.

SO_LINGER controla a ação executada quando dados não solicitados são enfileirados em um soquete e a função Close é chamada para fechar o soquete.

Por padrão, um soquete não pode ser associado (veja Bind) a um endereço local que já esteja em uso. Na ocasião, no entanto, pode ser desejável "reutilizar" um endereço dessa forma. Como cada conexão é identificada exclusivamente pela combinação de endereços locais e remotos, não há problema em ter dois soquetes associados ao mesmo endereço local, desde que os endereços remotos sejam diferentes.

Para informar a implementação do Windows Sockets de que uma chamada Bind em um soquete não deve ser permitida porque o endereço desejado já está em uso por outro soquete, o aplicativo deve definir a opção de soquete SO_REUSEADDR para o soquete antes de emitir a chamada Bind. Observe que a opção é interpretada somente no momento da chamada Bind: portanto, é desnecessário (mas inofensivo) definir a opção em um soquete que não deve ser associado a um endereço existente e definir ou redefinir a opção após a chamada Bind não ter efeito sobre esse ou qualquer outro soquete.

Um aplicativo pode solicitar que a implementação de Soquetes do Windows habilite o uso de pacotes "keep-alive" em conexões TCP (Protocolo de Controle de Transmissão) ativando a opção de soquete SO_KEEPALIVE. Uma implementação do Windows Sockets não precisa dar suporte ao uso de keep-alives: se isso acontecer, a semântica precisa é específica da implementação, mas deve estar em conformidade com a seção 4.2.3.6 do RFC 1122: "Requisitos para hosts da Internet – Camadas de comunicação". Se uma conexão for descartada como resultado de "keep-alives", o código de erro WSAENETRESET será retornado a todas as chamadas em andamento no soquete e as chamadas subsequentes falharão com WSAENOTCONN.

A opção TCP_NODELAY desabilita o algoritmo Nagle. O algoritmo Nagle é usado para reduzir o número de pacotes pequenos enviados por um host armazenando em buffer dados de envio não reconhecidos até que um pacote de tamanho completo possa ser enviado. No entanto, para alguns aplicativos, esse algoritmo pode impedir o desempenho e TCP_NODELAY pode ser usado para desativá-lo. Os gravadores de aplicativos não devem definir TCP_NODELAY, a menos que o impacto de fazer isso seja bem compreendido e desejado, pois a configuração TCP_NODELAY pode ter um impacto negativo significativo no desempenho da rede. TCP_NODELAY é a única opção de soquete com suporte que usa o nível IPPROTO_TCP; todas as outras opções usam o nível SOL_SOCKET.

Algumas implementações de Windows Sockets fornecem informações de depuração de saída se a opção SO_DEBUG for definida por um aplicativo.

As seguintes opções são suportadas para SetSockOpt. O Type identifica o tipo de dados endereçados por lpOptionValue.

As opções do Berkeley Software Distribution (BSD) para as quais não há suporte para SetSockOpt são:

CAsyncSocket::ShutDown

Chame essa função de membro para desabilitar envios, recebimentos ou ambos no soquete.

BOOL ShutDown(int nHow = sends);

Parâmetros

nHow
Um sinalizador que descreve quais tipos de operação não serão mais permitidos, usando os seguintes valores enumerados:

• receives = 0

• envios = 1

• both = 2

Valor de retorno

Diferente de zero se a função for bem-sucedida; caso contrário, 0 e um código de erro específico pode ser recuperado chamando GetLastError. Os seguintes erros se aplicam a essa função de membro:

• WSANOTINITIALISED Um AfxSocketInit bem-sucedido deve ocorrer antes de usar essa API.

• WSAENETDOWN A implementação do Windows Sockets detectou que o subsistema de rede falhou.

• WSAEINVAL nHow não é válido.

• WSAEINPROGRESS Uma operação de bloqueio do Windows Sockets está em andamento.

• WSAENOTCONN O soquete não está conectado (somente SOCK_STREAM).

• WSAENOTSOCK O descritor não é um soquete.

Comentários

ShutDown é usado em todos os tipos de soquetes para desabilitar a recepção, a transmissão ou ambos. Se nHow for 0, os recebimentos subsequentes no soquete serão não permitidos. Isso não tem efeito nas camadas de protocolo inferiores.

Para o protocolo TCP, a janela TCP não é alterada e os dados de entrada serão aceitos (mas não reconhecidos) até que a janela seja esgotada. Para Protocolo de Datagrama do Usuário (UDP), os datagramas de entrada são aceitos e enfileirados. Em nenhum caso será gerado um pacote de erro ICMP. Se nHow for 1, os envios subsequentes não serão permitidos. Para soquetes TCP, um FIN será enviado. A configuração nHow como 2 desabilita os envios e os recebimentos, conforme descrito acima.

Observe que ShutDown não fecha o soquete e os recursos anexados ao soquete não serão liberados até que Close seja chamado. Um aplicativo não deve depender de ser capaz de reutilizar um soquete depois de ser desligado. Em particular, uma implementação do Windows Sockets não é necessária para dar suporte ao uso de Connect nesse soquete.

Exemplo

Confira o exemplo de CAsyncSocket::OnReceive.

CASyncSocket::Socket

Aloca um identificador de soquete.

BOOL Socket(
    int nSocketType = SOCK_STREAM,
    long lEvent = FD_READ | FD_WRITE | FD_OOB | FD_ACCEPT | FD_CONNECT | FD_CLOSE,
    int nProtocolType = 0,
    int nAddressFormat = PF_INET);

Parâmetros

nSocketType
Especifica SOCK_STREAM ou SOCK_DGRAM.

lEvent
Uma máscara de bits, a qual especifica uma combinação de eventos de rede em que o aplicativo está interessado.

• FD_READ: deseja receber uma notificação de preparação para leitura.

• FD_WRITE: deseja receber uma notificação de preparação para escrita.

• FD_OOB: deseja receber uma notificação da chegada de dados fora da banda.

• FD_ACCEPT: deseja receber uma notificação de conexões de entrada.

• FD_CONNECT: deseja receber notificação de conexão concluída.

• FD_CLOSE: deseja receber uma notificação de fechamento do soquete.

nProtocolType
Protocolo a ser usado com o soquete específico para a família de endereços indicada.

nAddressFormat
Especificação da família de endereços.

Valor de retorno

Retornará TRUE se for bem-sucedido, FALSE em caso de falha.

Comentários

Esse método aloca um identificador de soquete. Ele não chama CAsyncSocket::Bind para associar o soquete a um endereço especificado, portanto, você precisa chamar Bind mais tarde para associar o soquete a um endereço especificado. Você pode usar CAsyncSocket::SetSockOpt para definir a opção de soquete antes que ela seja associada.

Confira também

Classe CObject
Gráfico da hierarquia
Classe CSocket
Classe CSocketFile