Collapse all Symbian^3 Product Developer Library

RHostResolver Class Reference

class RHostResolver : public RSubSessionBase

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.

Inherits from

RHostResolver
- RSubSessionBase

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

Member Functions 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

Parameters

const TSockAddr & anAddr	The address to use
TNameEntry & 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.
TRequestStatus & 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

Parameters

const TSockAddr & anAddr	The address to use
TNameEntry & 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.

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.

Parameters

const TDesC & 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
TNameEntry & 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.
TRequestStatus & 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

Parameters

const TDesC & 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
TNameEntry & 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.

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

Parameters

TDes & 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.

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

Parameters

TDes & 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.
TRequestStatus & 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.

Parameters

TNameEntry & aResult	Returns the next result of the name resolution.
TRequestStatus & 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.

Parameters

TNameEntry & aResult

Returns the next result of the name resolution.

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.

Parameters

RSocketServ & aSocketServer	The socket server session
TUint anAddrFamily	A constant identifying the protocol family
TUint aProtocol	A constant that identifies the protocol that provides the name resolution service

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.

Parameters

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

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

Parameters

const TDesC8 & aQuery	contains query data. The concrete type of the data depends on protocol. e.g. for tcpip it will imply DNS query.
TDes8 & aResult	Descriptor that will receive data. The concrete meaning of this data depends on protocol.
TRequestStatus & 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

Parameters

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

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.

Parameters

TDes8 & aResult	Descriptor that will receive data. The concrete meaning of this data depends on protocol.
TRequestStatus & 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.

Parameters

TDes8 & aResult

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

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

Parameters

const TDesC & aName

The local host name.

SetOpt(TUint, TUint, const TDesC8 &)

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

Parameters

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