RHostResolver Class Reference

#include <es_sock.h>

Link against: esock.lib

class RHostResolver : public RSubSessionBase

Inherits from

RHostResolver

Public Member Functions
IMPORT_C void	Cancel()
IMPORT_C void	Close()
IMPORT_C void	GetByAddress(const TSockAddr &, TNameEntry &, TRequestStatus &)
IMPORT_C TInt	GetByAddress(const TSockAddr &, TNameEntry &)
IMPORT_C void	GetByName(const TDesC &, TNameEntry &, TRequestStatus &)
IMPORT_C TInt	GetByName(const TDesC &, TNameEntry &)
IMPORT_C TInt	GetHostName(TDes &)
IMPORT_C void	GetHostName(TDes &, TRequestStatus &)
IMPORT_C void	Next(TNameEntry &, TRequestStatus &)
IMPORT_C TInt	Next(TNameEntry &)
IMPORT_C TInt	Open(RSocketServ &, TUint, TUint)
IMPORT_C TInt	Open(RSocketServ &, TUint, TUint, RConnection &)
IMPORT_C void	Query(const TDesC8 &, TDes8 &, TRequestStatus &)
IMPORT_C TInt	Query(const TDesC8 &, TDes8 &)
IMPORT_C void	QueryGetNext(TDes8 &, TRequestStatus &)
IMPORT_C TInt	QueryGetNext(TDes8 &)
IMPORT_C TInt	SetHostName(const TDesC &)
IMPORT_C TInt	SetOpt(TUint, TUint, const TDesC8 &)

Inherited Functions
	RSubSessionBase::CloseSubSession(TInt)
	RSubSessionBase::CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)
	RSubSessionBase::CreateSubSession(const RSessionBase &,TInt)
	RSubSessionBase::CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)
	RSubSessionBase::RSubSessionBase()
	RSubSessionBase::Send(TInt)const
	RSubSessionBase::Send(TInt,const TIpcArgs &)const
	RSubSessionBase::SendReceive(TInt)const
	RSubSessionBase::SendReceive(TInt,TRequestStatus &)const
	RSubSessionBase::SendReceive(TInt,const TIpcArgs &)const
	RSubSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
	RSubSessionBase::Session()const
	RSubSessionBase::SubSessionHandle()const

Detailed Description

Provides an interface to host name resolution services, such as DNS, that may be provided by particular protocol modules.

The interface provides functions to access the following facilities:

Obtaining names from addresses.

Obtaining addresses from names.

Getting and setting local host name.

Not all actual services provide all these facilities. You should also consult the documentation on the protocol you are intending to use. Functions return KErrNotSupported if the protocol does not support a given operation. Note that a description of the protocol family name resolution capabilities is available at run-time from TProtocolDesc::iNamingServices.

Before using any service, a connection to a socket server session must be made.

Each function is available in both synchronous and asynchronous versions.

A single RHostResolver can only perform one request of any type at once. A client is panicked if it makes two requests.

Member Function Documentation

Cancel ( )

IMPORT_C void

Cancel

(

)

Cancels any outstanding asynchronous calls, which will return with error code KErrCancel.

Close ( )

IMPORT_C void

(

)

Closes a name resolution service. If a service has been opened using Open(), then it should be closed using Close(). This will ensure all associated resources are released.

GetByAddress ( const TSockAddr &, TNameEntry &, TRequestStatus & )

IMPORT_C void	GetByAddress	(	const TSockAddr &	anAddr,
			TNameEntry &	aResult,
			TRequestStatus &	aStatus
		)

Get host by address (as get by name)

Gets the name of a host from its address asynchronously

capability: Dependent on the type of connection so deferred to PRT

Parameter	Description
anAddr	The address to use
aResult	On return, the result of the query. If more than one result is allowed by the protocol, the client can call Next() to find any further results.
aStatus	Indicates asynchronous operation and on completion contains an error code: see the system-wide error codes.

GetByAddress ( const TSockAddr &, TNameEntry & )

IMPORT_C TInt	GetByAddress	(	const TSockAddr &	anAddr,
			TNameEntry &	aResult
		)

Get host by address (as get by name)

Gets the name of a host from its address

capability: Dependent on the type of connection so deferred to PRT

Parameter	Description
anAddr	The address to use
aResult	Returns the result of the query. If more than one result is allowed by the protocol, the client can call Next() to find any further results.

Returns: KErrNone if successful otherwise another of the system-wide error codes.

GetByName ( const TDesC &, TNameEntry &, TRequestStatus & )

IMPORT_C void	GetByName	(	const TDesC &	aName,
			TNameEntry &	aResult,
			TRequestStatus &	aStatus
		)

Resolves a machine name to a TSockAddress asynchronously.

The server will fill in the supplied TNameEntry.

Parameter	Description
aName	The name to resolve. The format of the name and any wild-cards supported, along with any separators in hierarchical name systems, are protocol specific
aResult	On return, the result of the name resolution. If more than one result is allowed by the protocol, the client can call Next() to find any further results.
aStatus	Indicates asynchronous operation and, on completion, contains an error code: see the system-wide error codes.

GetByName ( const TDesC &, TNameEntry & )

IMPORT_C TInt	GetByName	(	const TDesC &	aName,
			TNameEntry &	aResult
		)

Resolves a machine name to a TSockAddress.

The server will fill in the supplied TNameEntry.

capability: Dependent on the type of connection so deferred to PRT

Parameter	Description
aName	The name to resolve. The format of the name and any wild-cards supported, along with any separators in hierarchical name systems, are protocol specific
aResult	On return, the result of the name resolution. If more than one result is allowed by the protocol, the client can call Next() to find any further results.

Returns: KErrNone if successful otherwise another of the system-wide error codes.

GetHostName ( TDes & )

IMPORT_C TInt

GetHostName

(

TDes &

aName

)

Gets the name of the local host.

Note that with some protocols the name of the local host is not necessarily known at all times. In some cases, a preceding call to SetHostName() must have been made.

capability: Dependent on the type of connection so deferred to PRT

Parameter	Description
aName	Returns the result of the query. The buffer passed in should have a minimum length of 256 characters, otherwise a panic may occur: you can use a parameter of the THostName type.

Returns: KErrNone if successful otherwise another of the system-wide error codes.

GetHostName ( TDes &, TRequestStatus & )

IMPORT_C void	GetHostName	(	TDes &	aName,
			TRequestStatus &	aStatus
		)

Gets the name of the local host asynchronously.

Note that with some protocols the name of the local host is not necessarily known at all times. In some cases, a preceding call to SetHostName() must have been made.

capability: Dependent on the type of connection so deferred to PRT

Parameter	Description
aName	Returns the result of the query. The buffer passed in should have a minimum length of 256 characters, otherwise a panic may occur: you can use a parameter of the THostName type.
aStatus	Indicates asynchronous operation and on completion contains an error code: see the system-wide error codes.

Next ( TNameEntry &, TRequestStatus & )

IMPORT_C void	Next	(	TNameEntry &	aResult,
			TRequestStatus &	aStatus
		)

Get the next response if there is more than one response for a given host name (alias list)

Returns the next answer asynchronously, where there is more than one response for a given host name.

For some protocols, GetByName() and GetByAddress() may find more than one answer, for example if aliases are allowed.

Parameter	Description
aResult	Returns the next result of the name resolution.
aStatus	Indicates asynchronous operation and on completion contains an error code: see the system-wide error codes.

Next ( TNameEntry & )

IMPORT_C TInt

(

TNameEntry &

aResult

)

Get the next response if there is more than one response for a given host name (alias list)

Returns the next answer where there is more than one response for a given host name.

For some protocols, GetByName() and GetByAddress() may find more than one answer, for example if aliases are allowed.

Parameter	Description
aResult	Returns the next result of the name resolution.

Returns: KErrNone if successful otherwise another of the system-wide error codes.

Open ( RSocketServ &, TUint, TUint )

IMPORT_C TInt	Open	(	RSocketServ &	aSocketServer,
			TUint	anAddrFamily,
			TUint	aProtocol
		)

Initialises a name resolution service provided by a particular protocol.

This must be called before other object functions are used.

Parameter	Description
aSocketServer	The socket server session
anAddrFamily	A constant identifying the protocol family
aProtocol	A constant that identifies the protocol that provides the name resolution service

Returns: KErrNone if successful otherwise another of the system-wide error codes.

Open ( RSocketServ &, TUint, TUint, RConnection & )

IMPORT_C TInt	Open	(	RSocketServ &	aSocketServer,
			TUint	anAddrFamily,
			TUint	aProtocol,
			RConnection &	aConnection
		)

Initialises a name resolution service provided by a particular protocol, and associates the service with the same interface as an existing RConnection instance.

This must be called before other object functions are used.

Note that the association is instantaneous, in that the Host Resolver is associated with the interface that the RConnection is associated with at the present time. This association terminates when the underlying interface goes down.

Parameter	Description
anAddrFamily	A constant identifying the protocol family.
aProtocol	A constant that identifies the protocol that provides the name resolution service.
aConnection	Existing RConnection whose interface this Host Resolver will be associated with.

Returns: KErrNone if successful otherwise another of the system-wide error codes.

Query ( const TDesC8 &, TDes8 &, TRequestStatus & )

IMPORT_C void	Query	(	const TDesC8 &	aQuery,
			TDes8 &	aResult,
			TRequestStatus &	aStatus
		)

Protocol - independent query. Asynchronous version.

capability: Dependent on the type of connection so deferred to PRT

Parameter	Description
aQuery	contains query data. The concrete type of the data depends on protocol. e.g. for tcpip it will imply DNS query.
aResult	Descriptor that will receive data. The concrete meaning of this data depends on protocol.
aStatus	indicates asynchronous operation, on completion contains a system-wide error code

Query ( const TDesC8 &, TDes8 & )

IMPORT_C TInt	Query	(	const TDesC8 &	aQuery,
			TDes8 &	aResult
		)

Protocol - independent query. Synchronous version.

capability: Dependent on the type of connection so deferred to PRT

Parameter	Description
aQuery	contains query data. The concrete type of the data depends on protocol. e.g. for tcpip it will imply DNS query.
aResult	Descriptor that will receive data. The concrete meaning of this data depends on protocol.

Returns: system-wide error code.

QueryGetNext ( TDes8 &, TRequestStatus & )

IMPORT_C void	QueryGetNext	(	TDes8 &	aResult,
			TRequestStatus &	aStatus
		)

Get the next query result. For some queries there can be more than one results. Asynchronous version.

Parameter	Description
aResult	Descriptor that will receive data. The concrete meaning of this data depends on protocol.
aStatus	indicates asynchronous operation, on completion contains a system-wide error code. In particular KErrNotFound means that there is no more information from resolver.

QueryGetNext ( TDes8 & )

IMPORT_C TInt

QueryGetNext

(

TDes8 &

aResult

)

Get the next query result. For some queries there can be more than one results. Synchronous version.

Parameter	Description
aResult	Descriptor that will receive data. The concrete meaning of this data depends on protocol.

Returns: system-wide error code. In particular KErrNotFound means that there is no more information from resolver.

SetHostName ( const TDesC & )

IMPORT_C TInt

SetHostName

(

const TDesC &

aName

)

Sets the name of the local host.

capability: NetworkControl Service restricting and stored at protocol level

Parameter	Description
aName	The local host name.

Returns: KErrNone if successful, otherwise another of the system-wide error codes.

SetOpt ( TUint, TUint, const TDesC8 & )

IMPORT_C TInt	SetOpt	(	TUint	anOptionName,
			TUint	anOptionLevel,
			const TDesC8 &	anOption = TPtrC8(NULL, 0)
		)