The THostInfoManager class (and its friend class THostInfoWindow) encapsulate the Winsock database functions gethostbyname(), gethostbyaddr(), and gethostname(). More...

#include <owl/wskhostm.h>

Public Member Functions
	THostInfoManager ()
	This function initializes the hidden window.

virtual	~THostInfoManager ()
	With this destructor, you need to clear any pending requests before the deletion.

int	GetLastError ()
	This function returns the last error code.

int	GetHostName (char *name, int nameLength=N_MAX_HOST_NAME)
	This function returns the name of the computer on which this program is running.

int	GetHostAddress (char szHostAddress, const char szHostName)
	This function effectively converts szHostName to szHostAddress.

int	GetHostAddress (TSocketAddress &sAddress, const char *szHostName)
	This function effectively converts szHostName to a socket address.

int	GetHostInfo (THostEntry *&hEntry, const TSocketAddress &sAddress)
	The caller of this function supplies a pointer to be assigned by this function.

int	GetHostInfo (THostEntry &hEntry, const char szName)
	Windows Sockets can block a call until the other end finishes the transaction.

int	GetHostInfoAsync (HANDLE &hTheHostRequest, TSocketAddress &sAddress)
	The TheHostRequest parameter is returned to the caller with the asynchrous request handle.

int	GetHostInfoAsync (HANDLE &hTheHostRequest, char *szName)
	Returns the same information as the other versions of GetHostInfoAsync.

int	GetHostInfoAsync (TWindow &wndNotify, HANDLE &hTheHostRequest, TSocketAddress &sAddress, uint nMessage=MSG_HOST_INFO_NOTIFY, char *chBuffer=0)
	This function notifies the given window that a request has completed.

int	GetHostInfoAsync (TWindow &wndNotify, HANDLE &hTheHostRequest, char szName, uint nMessage=MSG_HOST_INFO_NOTIFY, char chBuffer=0)
	This function notifies the given window that a request has completed, wndNotify is the window that will get the message that the request has completed.

int	CancelHostRequest (HANDLE hTheHostRequest=0)
	The caller can use this call to cancel the last pending request.

short	GetHostRequestCompleted ()
	This function returns true if the host completed the last requested transaction.

Static Public Member Functions
static int	HostEntryToAddress (THostEntry hEntry, char szAddress)
	Given a THostEntry*, this function converts it to a dotted-decimal szAddress.

static int	HostEntryToAddress (THostEntry *hEntry, TSocketAddress &sAddress)
	Given a THostEntry*, this function converts it to a socket address.

Protected Member Functions
void	SetHostRequestCompleted (int error)
	This function is called whenever an asynchronous request is completed.

Protected Attributes
bool	HostRequestCompleted
	Flag if host completed last request.

HANDLE	HostRequest
	Handle of host to get info about.

int	LastError
	Last error code.

char	HostInfoBuffer [MAXGETHOSTSTRUCT]
	Used for calls to WSAAsync...()

THostInfoWindow	HostWindow
	Hidden window to catch notifications.

Friends
class	THostInfoWindow

Detailed Description

The THostInfoManager class (and its friend class THostInfoWindow) encapsulate the Winsock database functions gethostbyname(), gethostbyaddr(), and gethostname().

These blocking (gethostby...) and non-blocking (gethostname) functions return information about the host in a hostent structure.

Definition at line 87 of file wskhostm.h.

Constructor & Destructor Documentation

◆ THostInfoManager()

owl::THostInfoManager::THostInfoManager ( )

This function initializes the hidden window.

Definition at line 101 of file wskhostm.cpp.

References owl::TWindow::Create(), HostInfoBuffer, HostRequest, HostRequestCompleted, HostWindow, and LastError.

◆ ~THostInfoManager()

owl::THostInfoManager::~THostInfoManager ( )

virtual

With this destructor, you need to clear any pending requests before the deletion.

Definition at line 121 of file wskhostm.cpp.

References CancelHostRequest(), HostRequest, and HostRequestCompleted.

Member Function Documentation

◆ CancelHostRequest()

int owl::THostInfoManager::CancelHostRequest ( HANDLE hTheHostRequest = 0 )

The caller can use this call to cancel the last pending request.

Definition at line 239 of file wskhostm.cpp.

References HostRequest, LastError, WINSOCK_ERROR, WINSOCK_NOERROR, owl::TWinSockDll::WSACancelAsyncRequest(), and owl::TWinSockDll::WSAGetLastError().

◆ GetHostAddress() [1/2]

int owl::THostInfoManager::GetHostAddress	(	char *	hostAddress,
		const char *	hostName )

This function effectively converts szHostName to szHostAddress.

If you have a name such as "joe_schmoe@borland.com" and you want the dotted-decimal IP address for it, you can call this function. This function assumes that there is enough space in szHostAddress for the address. This function, like most of Windows Sockets, currently works only with IP addresses. Thus, the szHostAddress is always going to be dotted-decimal format in Windows Sockets. Note that when using the inet_ntoa() function, the char* string returned resides in Windows Sockets memory space, the szHostAddress returned is allocated and owned by the caller of this function and can be manipulated any way the caller wants. This function returns an error value of WINSOCK_ERROR or WINSOCK_NOERROR.

Definition at line 156 of file wskhostm.cpp.

References GetHostInfo(), HostEntryToAddress(), and WINSOCK_ERROR.

◆ GetHostAddress() [2/2]

int owl::THostInfoManager::GetHostAddress	(	TSocketAddress &	address,
		const char *	hostName )

This function effectively converts szHostName to a socket address.

If you have a name such as "joe_schmoe@borland.com," and you want the TSocketAddress for it, you can call this function. This function, like most of Windows Sockets, currently works only with IP addresses. Thus, the szAddress is always going to be dotted-decimal format in Windows Sockets. The szHostName is a string parameter that specifies the host of which to get the address. This function returns an error value of WINSOCK_ERROR or WINSOCK_NOERROR.

Definition at line 175 of file wskhostm.cpp.

References GetHostInfo(), HostEntryToAddress(), and WINSOCK_ERROR.

◆ GetHostInfo() [1/2]

int owl::THostInfoManager::GetHostInfo	(	THostEntry *&	entry,
		const char *	name )

Windows Sockets can block a call until the other end finishes the transaction.

hEntry is a pointer passed by reference. The system will change that pointer to point to an internal Windows Sockets data structure. The contents must not be modified. szName is a preallocated string that holds a string. The address of the host can be in string format or in binary format.

The caller of this function passes a pointer to a THostEntry struct, for example:

THostEntry* tempTHostEntry;
GetHostInfo(tempTHostEntry, "JoeShmoe@anywhere.com");
printf("%s", tempTHostEntry->h_name); //h_name should be "joeSchmoe@anywhere.com"

Definition at line 226 of file wskhostm.cpp.

References owl::TWinSockDll::gethostbyname(), LastError, WINSOCK_ERROR, WINSOCK_NOERROR, and owl::TWinSockDll::WSAGetLastError().

◆ GetHostInfo() [2/2]

int owl::THostInfoManager::GetHostInfo	(	THostEntry *&	entry,
		const TSocketAddress &	address )

The caller of this function supplies a pointer to be assigned by this function.

The caller need not allocate space for any THostEntry structure. Because of this, the data needs to be read immediately or copied for later use. hEntry is a pointer passed by reference. sAddress is a preallocated SocketAddress reference. Due to the design of the socket API, the call to gethostbyaddr currently requires a pointer to the Internet address, rather than a sockaddr or even a sockaddr_in. Because passing a ulong pointer would most likely not work (for example, if the socket API were to support something other than IP), this issue is fixed by making a sockaddr interface to this API. The address is in network byte ordering.

Definition at line 197 of file wskhostm.cpp.

References owl::TWinSockDll::gethostbyaddr(), LastError, WINSOCK_ERROR, WINSOCK_NOERROR, and owl::TWinSockDll::WSAGetLastError().

◆ GetHostInfoAsync() [1/4]

int owl::THostInfoManager::GetHostInfoAsync	(	HANDLE &	theHostRequest,
		char *	name )

Returns the same information as the other versions of GetHostInfoAsync.

The difference is that the host name can be a string, rather than a TSocketAddress.

Definition at line 295 of file wskhostm.cpp.

References HostInfoBuffer, HostRequest, HostRequestCompleted, HostWindow, LastError, MSG_HOST_INFO_NOTIFY, WINSOCK_ERROR, WINSOCK_NOERROR, owl::TWinSockDll::WSAAsyncGetHostByName(), and owl::TWinSockDll::WSAGetLastError().

◆ GetHostInfoAsync() [2/4]

int owl::THostInfoManager::GetHostInfoAsync	(	HANDLE &	hostRequest,
		TSocketAddress &	address )

The TheHostRequest parameter is returned to the caller with the asynchrous request handle.

sAddress needs to be in network byte ordering. Note that due to the design of this class, you cannot have two outstanding service requests that get notified directly to this class. You can use the hwnd-specific notification version of this function to manage multiple requests. You can also create more than one instance of this class. The service is complete when HostRequestCompleted is true. Look at LastError in this case to see if there was an error.

Do not issue any asynchronous calls that post to this class hwnd until the previous request is completed. The alternative is to create multiple THostInfoManagers or manage the call-backs yourself. See the comments about the non-asynchronous version of this call (THostInfoManager::GetHostInfo) for more information.

Definition at line 273 of file wskhostm.cpp.

References HostInfoBuffer, HostRequest, HostRequestCompleted, HostWindow, LastError, MSG_HOST_INFO_NOTIFY, WINSOCK_ERROR, WINSOCK_NOERROR, owl::TWinSockDll::WSAAsyncGetHostByAddr(), and owl::TWinSockDll::WSAGetLastError().

◆ GetHostInfoAsync() [3/4]

int owl::THostInfoManager::GetHostInfoAsync	(	TWindow &	wndNotify,
		HANDLE &	hostRequest,
		char *	name,
		uint	message = MSG_HOST_INFO_NOTIFY,
		char *	buffer = 0 )

This function notifies the given window that a request has completed, wndNotify is the window that will get the message that the request has completed.

nMessage is the message that the wndNotify will receive. It defaults to MSG_HOST_INFO_NOTIFY, which is defined in the THostInfoManager's header file. hTheHostRequest is the asynchrous request handle that will be a reference to the request. szName is the name of the host, as in "coyote@acme.com." The chBuffer is a pointer to buffer that will be filled in with a hostent. It needs to be at least MAXGETHOSTSTRUCT bytes. If chBuffer is 0 (or not specified), the THostInfoManager's internal buffer will be used. The returned address is in network byte ordering.

Definition at line 360 of file wskhostm.cpp.

References HostInfoBuffer, HostRequest, HostRequestCompleted, LastError, WINSOCK_ERROR, WINSOCK_NOERROR, owl::TWinSockDll::WSAAsyncGetHostByName(), and owl::TWinSockDll::WSAGetLastError().

◆ GetHostInfoAsync() [4/4]

int owl::THostInfoManager::GetHostInfoAsync	(	TWindow &	wndNotify,
		HANDLE &	hostRequest,
		TSocketAddress &	address,
		uint	message = MSG_HOST_INFO_NOTIFY,
		char *	buffer = 0 )

This function notifies the given window that a request has completed.

nMessage is the message that the wndNotify will receive. It defaults to MSG_HOST_INFO_NOTIFY, which is defined in the THostInfoManager's header file. The chBuffer is a pointer to the buffer that will be filled in with a hostent. It needs to be at least MAXGETHOSTSTRUCT bytes. If chBuffer is 0 (or not specified), the THostInfoManager's internal buffer is used. The hTheHostRequest will hold a handle that the caller can use to reference the request on call-back. wParam will be equal to the hService returned. WSAGETSYNCERROR (lParam) holds an error, if any (0 is OK). WSAGETSYNCBUFLEN (lParam) holds actual length of the buffer. When this function returns, myTHostEntry holds the appropriate information. Since this information belongs to this object, you can delay reading it as long as you want. Note that while the sAddress should be passed in network byte ordering, the output on callback is also in network ordering.

Definition at line 325 of file wskhostm.cpp.

References HostInfoBuffer, HostRequest, HostRequestCompleted, LastError, WINSOCK_ERROR, WINSOCK_NOERROR, owl::TWinSockDll::WSAAsyncGetHostByAddr(), and owl::TWinSockDll::WSAGetLastError().

◆ GetHostName()

int owl::THostInfoManager::GetHostName	(	char *	name,
		int	nameLength = N_MAX_HOST_NAME )

This function returns the name of the computer on which this program is running.

The name parameter is set to the name. The return value is either WINSOCK_ERROR or WINSOCK_NOERROR. You can call THostInfoManager::GetLastError() to get the actual error value. name is a pointer to a preallocated buffer of minimum size of nameLength. nameLength should be at least N_MAX_HOST_NAME.

Definition at line 134 of file wskhostm.cpp.

References owl::TWinSockDll::gethostname(), LastError, WINSOCK_ERROR, WINSOCK_NOERROR, and owl::TWinSockDll::WSAGetLastError().

◆ GetHostRequestCompleted()

short owl::THostInfoManager::GetHostRequestCompleted ( )

inline

This function returns true if the host completed the last requested transaction.

Todo: really return a short? HostRequestCompleted is bool

Definition at line 158 of file wskhostm.h.

References HostRequestCompleted.

◆ GetLastError()

int owl::THostInfoManager::GetLastError ( )

inline

This function returns the last error code.

Definition at line 148 of file wskhostm.h.

References LastError.

◆ HostEntryToAddress() [1/2]

int owl::THostInfoManager::HostEntryToAddress	(	THostEntry *	entry,
		char *	address )

static

Given a THostEntry*, this function converts it to a dotted-decimal szAddress.

Because Windows Sockets supports only IP addressing, this function uses IP addressing and the address is always dotted-decimal. The return value is WINSOCK_ERROR or WINSOCK_NOERROR.

Definition at line 383 of file wskhostm.cpp.

References owl::TWinSockDll::inet_ntoa(), WINSOCK_ERROR, and WINSOCK_NOERROR.

◆ HostEntryToAddress() [2/2]

int owl::THostInfoManager::HostEntryToAddress	(	THostEntry *	entry,
		TSocketAddress &	address )

static

Given a THostEntry*, this function converts it to a socket address.

Because Windows Sockets supports only IP addressing, this function uses IP addressing and the address is an INetSocketAddress. The return value is WINSOCK_ERROR or WINSOCK_NOERROR.

Definition at line 402 of file wskhostm.cpp.

References STATIC_CAST, and WINSOCK_NOERROR.

◆ SetHostRequestCompleted()

void owl::THostInfoManager::SetHostRequestCompleted ( int result )

protected

This function is called whenever an asynchronous request is completed.

You may want to override this function in your THostInfoManager-derived class. If you do, you must call the base version.

Definition at line 414 of file wskhostm.cpp.

References HostRequestCompleted, and LastError.

Friends And Related Symbol Documentation

◆ THostInfoWindow

friend class THostInfoWindow

friend

Definition at line 126 of file wskhostm.h.

Member Data Documentation

◆ HostInfoBuffer

char owl::THostInfoManager::HostInfoBuffer[MAXGETHOSTSTRUCT]

protected

Used for calls to WSAAsync...()

Definition at line 121 of file wskhostm.h.

◆ HostRequest

HANDLE owl::THostInfoManager::HostRequest

protected

Handle of host to get info about.

Definition at line 119 of file wskhostm.h.

◆ HostRequestCompleted

bool owl::THostInfoManager::HostRequestCompleted

protected

Flag if host completed last request.

Definition at line 118 of file wskhostm.h.

◆ HostWindow

THostInfoWindow owl::THostInfoManager::HostWindow

protected

Hidden window to catch notifications.

Definition at line 122 of file wskhostm.h.

◆ LastError

int owl::THostInfoManager::LastError

protected

Last error code.

Definition at line 120 of file wskhostm.h.

The documentation for this class was generated from the following files:

include/owl/wskhostm.h
source/owlcore/wskhostm.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ THostInfoManager()

◆ ~THostInfoManager()

Member Function Documentation

◆ CancelHostRequest()

◆ GetHostAddress() [1/2]

◆ GetHostAddress() [2/2]

◆ GetHostInfo() [1/2]

◆ GetHostInfo() [2/2]

◆ GetHostInfoAsync() [1/4]

◆ GetHostInfoAsync() [2/4]

◆ GetHostInfoAsync() [3/4]

◆ GetHostInfoAsync() [4/4]

◆ GetHostName()

◆ GetHostRequestCompleted()

◆ GetLastError()

◆ HostEntryToAddress() [1/2]

◆ HostEntryToAddress() [2/2]

◆ SetHostRequestCompleted()

Friends And Related Symbol Documentation

◆ THostInfoWindow

Member Data Documentation

◆ HostInfoBuffer

◆ HostRequest

◆ HostRequestCompleted

◆ HostWindow

◆ LastError