#include <wskservm.h>

Public Member Functions
	TServiceManager ()
virtual	~TServiceManager ()
int	GetLastError ()
int	GetLastServiceCompletion ()
int	GetService (TServiceEntry &sEntry, uint16 nPort, const char szProtocol=0)
int	GetService (TServiceEntry &sEntry, const char szName, const char *szProtocol=0)
int	GetServicePort (char szName, uint16 &nPort, const char szProtocol=0)
int	GetServiceName (uint16 nPort, char szName, const char szProtocol=0)
int	GetServiceAsync (HANDLE &hService, uint16 nPort, const char *szProtocol=0)
int	GetServiceAsync (HANDLE &hService, char szName, const char szProtocol=0)
int	GetServiceAsync (TWindow &wndNotify, HANDLE &hService, uint16 nPort, const char szProtocol=0, uint nMessage=MSG_SERVICE_NOTIFY, char chBuffer=0)
int	GetServiceAsync (TWindow &wndNotify, HANDLE &hService, char szName, const char szProtocol=0, uint nMessage=MSG_SERVICE_NOTIFY, char *chBuffer=0)
int	CancelServiceRequest (HANDLE hService=0)
bool	GetServiceRequestCompleted ()
Protected Member Functions
void	ServiceCompleted (int nError)
Protected Attributes
int	LastError
int	OutstandingServiceRequests
bool	LastServiceRequestCompleted
char	ServiceBuffer [MAXGETHOSTSTRUCT]
HANDLE	LastServiceRequest
TServiceWindow	Window
Friends
class	TServiceWindow

Detailed Description

The TServiceManager class (and its friend class TServiceWindow) encapsulate the Winsock database functions getservbyname(), getservbyport(), WSAAsyncGetServByName(), and WSAAsyncGetServByPort(). These blocking (get...) and non-blocking (WSA...) functions return information about the service name, port, and protocol when given only a service name or a port.

Constructor & Destructor Documentation

owl::TServiceManager::TServiceManager ( )

This function creates the hidden window and initializes data members.

References owl::TWindow::Create(), LastError, LastServiceRequest, LastServiceRequestCompleted, OutstandingServiceRequests, ServiceBuffer, and Window.

owl::TServiceManager::~TServiceManager ( ) [virtual]

If there are any outstanding requests, this cancels them.

References CancelServiceRequest(), LastServiceRequest, and LastServiceRequestCompleted.

Member Function Documentation

int owl::TServiceManager::CancelServiceRequest ( HANDLE hService = 0 )

This function cancels a pending service that equals the hService. Note that if the service is 0 or unspecified, this function uses its own current service.

References LastError, LastServiceRequest, and OutstandingServiceRequests.

int owl::TServiceManager::GetLastError ( ) [inline]

This function returns the last error code.

References LastError.

int owl::TServiceManager::GetLastServiceCompletion ( ) [inline]

This function returns the last service completion.

Todo:: why int return type?

References LastServiceRequestCompleted.

int owl::TServiceManager::GetService	(	TServiceEntry *&	entry,
		const char *	name,
		const char *	protocol = `0`
	)

This function implements the blocking getservbyname(). sEntry is a pointer to a ServiceEntry*. If the caller does not allocate a ServiceEntry; it will be set by the system. Do not change any data in the returned structure. The szname argument points to the string representing the service name, such as ftp. It is generally case-sensitive. szProtocol is the protocol name, but may be passed as 0 to mean default or first found. The returned entry has the port in network byte order.

References LastError.

int owl::TServiceManager::GetService	(	TServiceEntry *&	entry,
		uint16	port,
		const char *	protocol = `0`
	)

Implements the blocking getservbyport(). sEntry is a pointer to a ServiceEntry*. The caller does not allocate a ServiceEntry; it will be set by the system. Do not change any data in the returned structure. port is passed to this function in network byte ordering. szProtocol is the protocol name, but may be passed as 0 to mean default or first found. The returned entry has the port in network byte order.

References LastError.

int owl::TServiceManager::GetServiceAsync	(	HANDLE &	hService,
		char *	name,
		const char *	protocol = `0`
	)

This call is nonblocking. It sets up a callback to its own member window. hService is a HANDLE reference. If the call is successful, it will hold the handle for the asynchrous call. Note that the caller can save the handle, but also that this class stores the handle for itself as well. port is passed into this function 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 may use the hwnd-specific notification version of this function to manage multiple requests at a time. You may also simply create more than one instance of this class. The service is complete when bServiceRequestCompleted is TRUE. You must look at nLastError in this case to see if there was an error.

References LastError, LastServiceRequest, LastServiceRequestCompleted, OutstandingServiceRequests, ServiceBuffer, and Window.

int owl::TServiceManager::GetServiceAsync	(	TWindow &	wndNotify,
		HANDLE &	hService,
		uint16	port,
		const char *	protocol = `0`,
		uint	message = `MSG_SERVICE_NOTIFY`,
		char *	buffer = `0`
	)

This function notifies the given wndNotify about the completion of the request. nMessage is the message that the hwndNotify will receive. It defaults to MSG_SERVICE_NOTIFY, which is defined in the TServiceManager's header file. The hService will hold a handle that the caller can use to reference the request on call-back. nPort should be passed in network byte ordering. The chBuffer is a pointer to buffer that will be filled in with a SERVENT. It needs to be at least MAXGETHOSTSTRUCT bytes. If chBuffer is 0 (or not specified), the TServiceManager's internal buffer will be used. szProtocol is the protocol name, but may be passed as 0 to mean default or first found. This class will NOT save the hServcice for itself. 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.

References LastError, LastServiceRequestCompleted, and ServiceBuffer.

int owl::TServiceManager::GetServiceAsync	(	TWindow &	wndNotify,
		HANDLE &	hService,
		char *	name,
		const char *	protocol = `0`,
		uint	message = `MSG_SERVICE_NOTIFY`,
		char *	buffer = `0`
	)

This function notifies the given wndNotify about the completion of the request. nMessage is the message that the hwndNotify will receive. It defaults to MSG_SERVICE_NOTIFY, which is defined in the TServiceManager's header file. The hService will hold a handle that the caller can use to reference the request on call-back. The chBuffer is a pointer to a buffer that will be filled in with a SERVENT. It needs to be at least MAXGETHOSTSTRUCT bytes. If chBuffer is 0 (or not specified), the TServiceManager's internal buffer will be used. szName is a pointer to a c string service name, such as ftp. szProtocol is the protocol name, but may be passed as 0 to mean default or first found. This class will NOT save the hService for itself. 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.

References LastError, LastServiceRequestCompleted, and ServiceBuffer.

int owl::TServiceManager::GetServiceAsync	(	HANDLE &	hService,
		uint16	port,
		const char *	protocol = `0`
	)

This call is non-blocking. It sets up a callback to its own member window. hService is a HANDLE reference. If the call is successful, it will hold the handle for the asynchrous call. Note that the caller can save the handle, but also that this class stores the handle for itself as well. port is passed into this function 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 may use the hwnd-specific notification version of this function to manage multiple requests at a time. You may also simply create more than one instance of this class. The service is complete when bServiceRequestCompleted is TRUE. You must look at nLastError in this case to see if there was an error.

References LastError, LastServiceRequest, LastServiceRequestCompleted, OutstandingServiceRequests, ServiceBuffer, and Window.

int owl::TServiceManager::GetServiceName	(	uint16	port,
		char *	name,
		const char *	protocol = `0`
	)

This function is blocking. The szName needs to be big enough to hold the service's name (N_MAX_SERVICE_NAME). The port must be passed in network byte ordering. szProtocol is the protocol name, but may be passed as 0 to mean default or first found.

References GetService().

int owl::TServiceManager::GetServicePort	(	char *	name,
		uint16 &	port,
		const char *	protocol = `0`
	)

This function is blocking. Given an input service in szName, this function fills nPort with the port (in network order). The port is a reference to an int. If the call returns OK, this will be the port in network ordering. szProtocol is the protocol name, but may be passed as 0 to mean default or first found.

References GetService().

bool owl::TServiceManager::GetServiceRequestCompleted ( ) [inline]

This function returns true if the last service requested has been completed.

References LastServiceRequestCompleted.

void owl::TServiceManager::ServiceCompleted ( int error ) [protected]

This function is called whenever an internal window callback is used for an asynchronous call. When this function is called, the ServiceRequestCompleted member is true (it got set to true right before this function was called). You may want to override this function. If you do, you must call the base version.

References LastError, LastServiceRequestCompleted, and OutstandingServiceRequests.