VB Socket Class


Topics:

Overview
Conditional Directives
Constants
Type Definitions
Enumerations
Functions


Overview

The vbSocket class is used to create TCP/IP sockets. The vbSocket class supports stream sockets and datagram sockets It includes several low-level functions needed by derived classes to establish communication end-points and transfer data.


Conditional Directives

__BSD_UNIX__ - Conditional directive required for BSD include files.

__UNIX__ - Conditional directive required for all UNIX variants.

__WIN32__ - Conditional directive required for all WIN32 platforms


Constants

const unsigned vbsBUF_SIZE     =  1024; // Fixed string buffer length
const unsigned vbsMAX_NAME_LEN =  255;  // Maximum string name length


Type Definitions

vbsAddressFamily - Type definition used to represent the address family to which a socket belongs.

vbsProtocolFamily - Type definition used to represent the protocol family to which a socket belongs.

vbsSocket_t - Type used to ID sockets.

vbsPort_t - Type used for port numbers.

vbsSocketAddress - Type used to for a socket Internet address.

vbsServent - Type definition used for service name and protocol information.

vbsHostNameInfo - Type definition used for host name information


Enumerations

enum vbsSocketError {    // vbSocket exception codes
  vbSOCKET_NO_ERROR = 0,       // No socket errors reported
  vbSOCKET_INVALID_ERROR_CODE, // Invalid socket error code

  // Socket error codes
  vbSOCKET_ACCEPT_ERROR,         // Error accepting remote socket
  vbSOCKET_BIND_ERROR,           // Could not bind socket
  vbSOCKET_CONNECT_ERROR,        // Could not connect socket
  vbSOCKET_HOSTNAME_ERROR,       // Could not resolve hostname
  vbSOCKET_INIT_ERROR,           // Initialization error
  vbSOCKET_LISTEN_ERROR,         // Listen error
  vbSOCKET_PROTOCOL_ERROR,       // Unknown protocol requested
  vbSOCKET_RECEIVE_ERROR,        // Receive error
  vbSOCKET_SERVICE_ERROR,        // Unknown service requested
  vbSOCKET_SOCKETTYPE_ERROR,     // Unknown socket type requested
  vbSOCKET_TRANSMIT_ERROR,       // Transmit error

  // WIN32 WinSock Error Codes (Transparent to UNIX applications)
  vbSOCKET_WINSOCKCLEANUP_ERROR, // WSACleanup operation failed
  vbSOCKET_WINSOCKEINVAL_ERROR,  // Version not supported by DLL
  vbSOCKET_WINSOCKINIT_ERROR,    // Could not initialize Winsock
  vbSOCKET_WINSOCKNETWORK_ERROR, // Network subsystem is not ready
  vbSOCKET_WINSOCKVERSION_ERROR, // Requested version not supported
  
  // Exception codes added to handle variable block errors
  vbSOCKET_BLOCKACK_ERROR,    // Variable block acknowledgment error
  vbSOCKET_BLOCKHEADER_ERROR, // Bad variable block header
  vbSOCKET_BLOCKSIZE_ERROR,   // Bad variable block size
  vbSOCKET_BLOCKSYNC_ERROR    // Variable block synchronization error
};

enum vbsSocketLibraryVersion {
  // Platform specific library version constants

  // WIN32 supported WSA versions. NOTE: The WSA constants have no
  // meaning in UNIX implementations but will work transparently in
  // all UNIX applications.
  vbSOCKET_WSAVER_ONEZERO, // Testing purposes only
  vbSOCKET_WSAVER_ONEONE,  // Windows 95A/B/C, 98, 98SE, NT4.0 
  vbSOCKET_WSAVER_TWOZERO, // Windows 98, 98SE, 2000 compatible
  vbSOCKET_WSAVER_TWOTWO   // Windows 98SE, 2000 compatible
};

enum vbsServices {
  // Common port assignments
  vbSOCKET_FTP_PORT        = 21,  // tcp ftp port
  vbSOCKET_TELNET_PORT     = 23,  // tcp telnet port
  vbSOCKET_SMTP_PORT       = 25,  // tcp simple mail transfer protocol
  vbSOCKET_TIME_PORT       = 37,  // tcp time server
  vbSOCKET_NAME_PORT       = 42,  // tcp name server
  vbSOCKET_NAMESERVER_PORT = 53,  // tcp domain name server
  vbSOCKET_FINGER_PORT     = 79,  // tcp finger port
  vbSOCKET_HTTP_PORT       = 80,  // tcp http port
  vbSOCKET_POP_PORT        = 109, // tcp postoffice protocol
  vbSOCKET_POP2_PORT       = 109, // tcp postoffice protocol
  vbSOCKET_POP3_PORT       = 110, // tcp postoffice protocol
  vbSOCKET_NNTP_PORT       = 119, // tcp network news transfer protocol

  // vbsSocket default port assignment
  vbsDEFAULT_PORT = 3000 // Value used if no port is assigned
};

enum vbsServerTypes {
  vbSOCKET_STREAM_SERVER,
  vbSOCKET_DATAGRAM_SERVER,
  vbSOCKET_SERIAL_PORT_SERVER,
  vbSOCKET_HTTP_SERVER,
  vbSOCKET_LOCAL_FILE_SYSTEM
};

enum vbClientTypes {
  vbSOCKET_STREAM_CLIENT,
  vbSOCKET_DATAGRAM_CLIENT,
  vbSOCKET_HTTP_CLIENT,
  vbSOCKET_SERIAL_PORT_CLIENT
};


Functions

vbSocket::vbSocket()
vbSocket::~vbSocket()
vbSocket::Accept()
vbSocket::Bind()
vbSocket::BytesMoved()
vbSocket::BytesRead()
vbSocket::Close()
vbSocket::CloseRemoteSocket()
vbSocket::CloseSocket()
vbSocket::Connect()
vbSocket::GetAddressFamily()
vbSocket::GetBoundSocket()
vbSocket::GetClientInfo()
vbSocket::GetHostName()
vbSocket::GetPortNumber()
vbSocket::GetProtocolFamily()
vbSocket::GetRemoteAddressFamily()
vbSocket::GetRemoteHostName()
vbSocket::GetRemotePortNumber()
vbSocket::GetRemoteSocket()
vbSocket::GetServByName()
vbSocket::GetServByPort()
vbSocket::GetSockName()
vbSocket::GetSocket()
vbSocket::GetSocketError()
vbSocket::GetSocketType()
vbSocket::InitSocket()
vbSocket::InitSocketLibrary()
vbSocket::IsBound()
vbSocket::IsConnected()
vbSocket::Listen()
vbSocket::RawRead()
vbSocket::RawReadFrom()
vbSocket::RawRemoteRead()
vbSocket::RawRemoteWrite()
vbSocket::RawWrite()
vbSocket::RawWriteTo()
vbSocket::Recv()
vbSocket::RecvFrom()
vbSocket::ReleaseSocketLibrary()
vbSocket::RemoteRecv()
vbSocket::RemoteSend()
vbSocket::ResetError()
vbSocket::ResetRead()
vbSocket::ResetSocketError()
vbSocket::ResetWrite()
vbSocket::Send()
vbSocket::SendTo()
vbSocket::SetAddressFamily()
vbSocket::SetPortNumber()
vbSocket::SetProtocolFamily()
vbSocket::SetSocketError()
vbSocket::SetSocketType()
vbSocket::ShutDown()
vbSocket::ShutDownRemoteSocket()
vbSocket::ShutDownSocket()
vbSocket::Socket()
vbSocket::SocketExceptionMessage()

vbSocket::vbSocket() - Socket constructor that performs no initialization other then setting default values for the socket data members.

vbSocket::vbSocket(vbsSocket_t st, vbsPort_t port, char *hostname = 0) - Socket constructor used to initialize the socket according to the socket type: SOCK_STREAM or SOCK_DGRAM. All ports below 1024 are reserved. A hostname name should only be specified for client sockets.

virtual vbSocket::~vbSocket() - Class destructor used to automatically close an open socket when a vbSocket object is deleted.

vbsSocket_t vbSocket::Accept() - Public member function used to accept a connect from a remote socket. An Accept() call blocks the server until the a client requests service. Returns a valid socket descriptor or -1 if an error occurs.

int vbSocket::Bind() - Public member function used to bind the socket to a name so that other processes can reference it and allow this socket to receive messages. Returns -1 if an error occurs.

int vbSocket::BytesMoved() - Public member function that return the total number of bytes moved following a write operation.

int vbSocket::BytesRead() - Public member function that return the total number of bytes read following a read operation.

void vbSocket::Close() - Public member function used to close any and un-initialize any bound sockets.

void vbSocket::Close(vbsSocket_t s) - Public member function used to close the specified socket.

void vbSocket::CloseRemoteSocket() - Public member function used to close the client socket.

void vbSocket::CloseSocket() - Public member function used to close the server side socket.

int vbSocket::Connect() - Public member function used to connect the socket to a client or server. On the client side a connect call is used to initiate a connection. Returns -1 if an error occurs.

vbsAddressFamily vbSocket::GetAddressFamily() - Public member function used to retrieve the current address family.

vbsSocket_t vbSocket::GetBoundSocket() - Public member function used to retrieve the currently bound socket.

void vbSocket::GetClientInfo(char *client_name, int &r_port) - Public member function used to get the client's host name and port number. NOTE: This function assumes that a block of memory equal to the vbsMAX_NAME_LEN constant has already been allocated.

int vbSocket::GetHostName(char *hs) - Public member function that passes back the host name of this machine in the "hs" variable. NOTE: A memory buffer equal to vbsMAX_NAME_LEN must be pre-allocated prior to using this function. Return -1 is an error occurs.

int vbSocket::GetPortNumber() - Public member function that returns port number actually set by the system. Use this function after a call to vbSocket::GetSockName();

vbsProtocolFamily vbSocket::GetProtocolFamily() - Public member function used to retrieve the current protocol family.

vbsAddressFamily vbSocket::GetRemoteAddressFamily() - Public member function used to retrieve the current address family.

int vbSocket::GetRemoteHostName(char *hs) - Public member function that passes back the host name the client in the "hs" variable. NOTE: A memory buffer equal to vbsMAX_NAME_LEN must be pre-allocated prior to using this function. Return -1 is an error occurs.

int vbSocket::GetRemotePortNumber() - Public member function that returns the port number of the client socket.

vbsSocket_t vbSocket::GetRemoteSocket() - Public member function used to retrieve the client side socket.

int vbSocket::GetServByName(char *name, char *protocol = 0) - Public member function used to get service information corresponding to a service name and protocol. Returns -1 if an unknown service or protocol is requested.

int vbSocket::GetServByPort(int port, char *protocol = 0) - Public member function used to get service information corresponding to a port number and protocol. Returns -1 if an unknown service or protocol is requested.

int vbSocket::GetSockName() - Public member function used to retrieve the current name of the socket descriptor. It is used on a bound and/or connected socket and returns the local association. This function is especially useful when a connect call has been made without doing a bind first in which case this function provides the only means by which you can determine the local association which has been set by the system. Returns -1 if an error occurs.

vbsSocket_t vbSocket::GetSocket() - Public member function used to retrieve the socket.

vbsSocketError vbSocket::GetSocketError() - Public member function used to retrieve the last reported socket error. The return value will correspond to one of the integer constants defined in the error code enumeration.

vbsSocketError vbSocket::GetSocketError() const - Public member function used to retrieve the last reported socket error. The return value will correspond to one of the integer constants defined in the error code enumeration.

vbsSocket_t vbSocket::GetSocketType() - Public member function used to retrieve the current socket type: SOCK_STREAM or SOCK_DGRAM.

vbsSocket_t vbSocket::InitSocket(vbsSocket_t st, int port, char *hostname = 0) - Public member function used to create a and initialize a socket according to the socket type: SOCK_STREAM or SOCK_DGRAM. All ports below 1024 are reserved. The "hostname" variable is an optional parameter that allows clients to specify a server name. Returns a valid socket descriptor or -1 if the socket cannot be initialized.

int vbSocket::InitSocketLibrary() - Public member function used to perform any platform specific initialization required before network communication can be established. Returns zero if no errors occur, -1 if an error occurs and the error can be mapped internally, or a value greater then zero if an error occurs and the error cannot be determined.

int vbSocket::IsBound() - Public member function that returns true if the socket is currently bound.

int vbSocket::IsConnected() - Public member function that returns true if the socket is currently connected.

int vbSocket::Listen(int max_connections = SOMAXCONN) - Public member function used to listen for connections if configured as a server. The "max_connections" variable determines how many pending connections the queue will hold. Returns -1 if an error occurs.

int vbSocket::RawRead(void *buf, int bytes, int flags = 0) - Public member function used to receive a block of data from the bound socket. NOTE: A raw read may return before all the bytes have been read. Returns the total number of bytes read or -1 if an error occurs.

int vbSocket::RawRead(vbsSocket_t s, void *buf, int bytes, int flags = 0) - Public member function used to receive a block of data from a specified socket. NOTE: A raw read may return before all the bytes have been read. Returns the total number of bytes read or -1 if an error occurs.

int vbSocket::RawReadFrom(vbsSocket_t s, vbsSocketAddress *sa, void *buf,int bytes, int flags = 0) - Public member function used to receive a block of data from a remote datagram socket. NOTE: A raw read may return before all the bytes have been read. Returns the total number of bytes read or -1 if an error occurs.

int vbSocket::RawReadFrom(void *buf, int bytes, int flags = 0) - Public member function used to receive a block of data from a remote datagram socket. NOTE: A raw read may return before all the bytes have been read. Returns the total number of bytes read or -1 if an error occurs.

int vbSocket::RawRemoteRead(void *buf, int bytes, int flags = 0) - Public member function used to receive a block of data from a remote socket. NOTE: A raw read may return before all the bytes have been read. Returns the total number of bytes read or -1 if an error occurs.

int vbSocket::RawRemoteWrite(const void *buf, int bytes, int flags = 0) - Public member function used to send a block of data to a remote socket. NOTE: A raw write may return before all the bytes have been written. Returns the total of bytes written or -1 if an error occurs.

int vbSocket::RawWrite(const void *buf, int bytes, int flags = 0) - Public member function used to send a block of data to the bound socket. NOTE: A raw write may return before all the bytes have been written. Returns the total of bytes written or -1 if an error occurs.

int vbSocket::RawWrite(vbsSocket_t s, const void *buf, int bytes, int flags = 0) - Public member function used to send a block of data to a specified socket. NOTE: A raw write may return before all the bytes have been written. Returns the total of bytes written or -1 if an error occurs.

int vbSocket::RawWriteTo(vbsSocket_t s, vbsSocketAddress *sa, void *buf,int bytes, int flags = 0) - Public member function used to send a block of data to a datagram socket. NOTE: A raw write may return before all the bytes have been written. Returns the total of bytes written or -1 if an error occurs.

int vbSocket::RawWriteTo(void *buf, int bytes, int flags = 0) - Public member function used to send a block of data to a datagram socket. NOTE: A raw write may return before all the bytes have been written. Returns the total of bytes written or -1 if an error occurs.

int vbSocket::Recv(void *buf, int bytes, int flags = 0) - Public member function used to receive a block of data from the bound socket and does not return until all the bytes have been read. Returns the total number of bytes received or -1 if an error occurs.

int vbSocket::Recv(vbsSocket_t s, void *buf, int bytes, int flags = 0) - Public member function used to receive a block of data from a specified socket and does not return until all the bytes have been read. Returns the total number of bytes received or -1 if an error occurs.

int vbSocket::RecvFrom(vbsSocket_t s, vbsSocketAddress *sa, void *buf,int bytes, int flags = 0) - Public member function receive a block of data from a remote datagram socket and does not return until all the bytes have been read. Returns the total number of bytes received or -1 if an error occurs.

int vbSocket::RecvFrom(void *buf, int bytes, int flags = 0) - Public member function receive a block of data from a remote datagram socket and does not return until all the bytes have been read. Returns the total number of bytes received or -1 if an error occurs.

int vbSocket::ReleaseSocketLibrary() - Public member function used to perform any platform specific operations required to release the socket library and free any resources associated with it. Returns -1 if any errors occur.

int vbSocket::RemoteRecv(void *buf, int bytes, int flags = 0) - Public member function used to receive a block of data from a remote socket in blocking mode. Returns the total number of bytes received or -1 if an error occurs.

int vbSocket::RemoteSend(const void *buf, int bytes, int flags = 0) - Public member function used to send a block of data to a remote socket in blocking mode. Returns the total number of bytes received or -1 if an error occurs.

void vbSocket::ResetError() - Public member function used to clear the last reported socket error.

void vbSocket::ResetRead() - Public member function used to reset the received byte count.

void vbSocket::ResetSocketError() - Public member function used to clear the last reported socket error.

void vbSocket::ResetWrite() - Public member function used to reset the transmit byte count.

int vbSocket::Send(const void *buf, int bytes, int flags = 0) - Public member function used to send a block of data to the bound socket and does not return until all the bytes have been written. Returns the total number of bytes sent or -1 if an error occurs.

int vbSocket::Send(vbsSocket_t s, const void *buf, int bytes, int flags = 0) - Public member function used to send a block of data to a specified socket and do not return until all the bytes have been written. Returns the total number of bytes sent or -1 if an error occurs.

int vbSocket::SendTo(vbsSocket_t s, vbsSocketAddress *sa, void *buf,int bytes, int flags = 0) - Public member function used to send a block of data to a datagram socket and does not return until all the bytes have been written. Returns the total number of bytes sent or -1 if an error occurs.

int vbSocket::SendTo(void *buf, int bytes, int flags = 0) - Public member function used to send a block of data to a datagram socket and does not return until all the bytes have been written. Returns the total number of bytes sent or -1 if an error occurs.

void vbSocket::SetAddressFamily(vbsAddressFamily af) - Public member function used to set the address family. Defaults to AF_INET when a new vbSocket object is constructed.

void vbSocket::SetPortNumber(vbsPort_t p) - Public member function used to set the port number.

void vbSocket::SetProtocolFamily(vbsProtocolFamily pf) - Public member function used to set the protocol family. Defaults to IPPROTO_TCP when a new vbSocket object is constructed.

void vbSocket::SetSocketError(vbsSocketError err) - Public member function used to set the socket error code. The "err" variable must correspond to one to the integer constants defined in the error code enumeration.

void vbSocket::SetSocketType(vbsSocket_t st) - Public member function used to set the socket type. Defaults to SOCK_STREAM when a new vbSocket object is constructed.

void vbSocket::ShutDown(int how = 0) - Public member function used to close and un-initialize a full-duplex socket. The "how" variable must equal one of the following values: 0 = user is no longer interested in reading data, 1 = no more data will be sent, or 2 = no data is to be sent or received.

void vbSocket::ShutDown(vbsSocket_t s, int how = 0) - Public member function used to close and un-initialize the specified full-duplex socket. The "how" variable must equal one of the following values: 0 = user is no longer interested in reading data, 1 = no more data will be sent, or 2 = no data is to be sent or received.

void vbSocket::ShutDownRemoteSocket(int how = 0) - Public member function used to close a full-duplex client side socket. The "how" variable must equal one of the following values: 0 = user is no longer interested in reading data, 1 = no more data will be sent, or 2 = no data is to be sent or received.

void vbSocket::ShutDownSocket(int how = 0) - Public member function used to close a full-duplex server side socket. The "how" variable must equal one of the following values: 0 = user is no longer interested in reading data, 1 = no more data will be sent, or 2 = no data is to be sent or received.

vbsSocket_t vbSocket::Socket() - Public member function used to create a socket. Returns a valid socket descriptor or -1 if the socket cannot be initialized.

const char *vbSocket::SocketExceptionMessage() - Public member function that returns a null-terminated string that can be use to log or print a socket exception.


End Of Document