CSimpleSocket : CDummyFile

$Revision: 60 $

Description

This class is inherited from CDummyFile. When I first saw the socket API, it seemed to be the fruit of a weird, twisted mind. Then I remembered sockets came from the Unix world. No one ever accused of Unix being straightforward. With this in mind I wrote CSimpleSocket to try to bring some sanity to sockets. There are two parts to a socket. The IP address and a port number.

Data Members

Address - The "dotted" IP address. Example: "20.2.1.3"

Name - The name of the machine. This will be empty if the address has no name.

AliasList - This contains the alternate names for the IP address. Some machines have multiple names.

Methods

void Close( void )
Closes the socket. 
void GetAddress( CString& dotted_ip_address_string ) const
Retrieves the Address data member. 
SOCKET GetID( void ) const
Retrieves the Socket ID so you can call the socket API directly. 
void GetMyAddress( CString& dotted_ip_address_string )
Retrieves your IP address. 
void GetMyName( CString& machine_name )
Retrieves your IP host name. 
void GetName( CString& host_name ) const
Retrieves the Name data member. 
DWORD GetOptions( void ) const
Returns the options for this socket. See SetOptions() for a list of valid options bits. Combine the options together with the OR operator. 
void GetPort( short& port_number ) const
void GetPort( CString& port_name ) const
Retrieves the port number or port name of this socket. For example, if you have a telnet socket (i.e. port number 23), GetPort will return 23 in port_number and "telnet" in port_name. If no name can be found for the port number, port_name will be filled with a string representation of the port number. 
TCHAR GetStringReadTerminatorCharacter( void ) const
Returns the character that will cause a Read() to terminate when reading a CString. 
BOOL IsBroken( void ) const
Returns TRUE if the socket is broken. 
BOOL IsDataWaiting( void )
Returns TRUE if there are bytes waiting to be Read(). 
BOOL Open( void ) = 0
BOOL Open( LPCTSTR machine_name_or_address, UINT port_number = 23, CFileException * = NULL ) = 0
Pure virtual function that opens the socket. You have to implement these functions. 
void Read( CString& line_to_read )
UINT Read( VOID * buffer, UINT maximum_number_of_bytes_to_read )
Pulls data out of the socket. If you are reading a string, the character set by SetStringReadTerminatorCharacter() will terminate the read. A NULL (character zero) will always terminate a string read. This function will block the execution of the thread until the other side of the socket writes something. You can cause the read to return after a time period has expired and no data has arrived, see SetReadTimeout(). 
void SetAddress( LPCTSTR address )
This sets the Address, Name and AliasList data members. You use either a "dotted" IP address or a machine name, SetAddress will figure out what you mean. 
void SetID( const SOCKET socket_id )
Use this function if you've created a socket using the native socket API and want to play with it via CSimpleSocket. It does not set any of the address/name members. If the class is allready being used to play with an existing socket, it will be closed before the socket_id is attached. 
void SetName( LPCTSTR machine_name )
Simply sets the Name member. 
void SetOptions( DWORD options )
Simply sets the options for the socket. This is useful only before opening the socket. These are the valid options: 
void SetPort( const short port_number )
void SetPort( const char * port_name )
Sets the port number and name. 
void SetReadTimeout( DWORD number_of_milliseconds )
Sets the number of milliseconds before a Read() call will timeout. This is how you solve the problem of both sides of a socket connection reading from the socket at the same time. Since neither one is writing to the socket, the read will never return, resulting in a deadlock. 
void SetStringReadTerminatorCharacter( TCHAR character )
Sets the character that will terminate a string Read(). A NULL (character zero) will always terminate a string read. 
void SetWriteTimeout( DWORD number_of_milliseconds )
Sets the number of milliseconds before a Write() call will timeout. 
void StartWindowsSockets( void )
Starts sockets. It is not recommended that you call this function. CSimpleSocket will call it as needed. 
void StopWindowsSockets( void )
Stops sockets. It is not recommended that you call this function. CSimpleSocket will call it as needed. 
void TranslateErrorCode( DWORD error_code, LPSTR destination_string, DWORD size_of_string )
Did you ever wonder what 10014 means? This function translates a socket error code into something humanly readable. 
BOOL Transmit( CFile& file_to_send, DWORD flags = TF_DISCONNECT, CByteArray * send_before = NULL, CByteArray * send_after )
Will transmit the file_to_send down the socket. If you want to send some bytes before the file, set send_before to the address of a CByteArray. If you want some bytes sent after the file, set send_after to the address of a CByteArray. Read up on the TransmitFile() API for a discussion of the flags parameter. 
void Write( const CString& string_to_write )
void Write( const VOID * buffer, const long number_of_bytes_to_write )
Sends data out of the socket.

Example

#include <wfc.h>
#pragma hdrstop

int close_the_socket( CSimpleSocket& the_socket )
{
   WFCTRACEINIT( TEXT( "close_the_socket()" ) );

   DWORD socket_options = the_socket.GetOptions();

   if ( socket_options & optionsDontResolveHostName )
   {
      WFCTRACE( TEXT( "Host name was not resolved." ) );
   }

   if ( socket_options & optionsDontResolvePortNumber )
   {
      WFCTRACE( TEXT( "Port number was not resolved." ) );
   }

   the_socket.Close();

   // OK, this is a really lame sample but the class
   // is pure virtual!
}

API's Used

CSimpleSocket uses the following API's:
Copyright, 2000, Samuel R. Blackburn
$Workfile: sockets.cpp $
$Modtime: 6/26/01 10:56a $