RHostResolver Class Reference

#include <es_sock.h>

Link against: esock.lib

class RHostResolver : public RSubSessionBase

Inherits from

Public Member Functions
IMPORT_C voidCancel()
IMPORT_C voidClose()
IMPORT_C voidGetByAddress(const TSockAddr &, TNameEntry &, TRequestStatus &)
IMPORT_C TIntGetByAddress(const TSockAddr &, TNameEntry &)
IMPORT_C voidGetByName(const TDesC &, TNameEntry &, TRequestStatus &)
IMPORT_C TIntGetByName(const TDesC &, TNameEntry &)
IMPORT_C TIntGetHostName(TDes &)
IMPORT_C voidGetHostName(TDes &, TRequestStatus &)
IMPORT_C voidNext(TNameEntry &, TRequestStatus &)
IMPORT_C TIntNext(TNameEntry &)
IMPORT_C TIntOpen(RSocketServ &, TUint, TUint)
IMPORT_C TIntOpen(RSocketServ &, TUint, TUint, RConnection &)
IMPORT_C voidQuery(const TDesC8 &, TDes8 &, TRequestStatus &)
IMPORT_C TIntQuery(const TDesC8 &, TDes8 &)
IMPORT_C voidQueryGetNext(TDes8 &, TRequestStatus &)
IMPORT_C TIntQueryGetNext(TDes8 &)
IMPORT_C TIntSetHostName(const TDesC &)
IMPORT_C TIntSetOpt(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 voidCancel()

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

Close ( )

IMPORT_C voidClose()

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 voidGetByAddress(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

Parameters
anAddrThe address to use
aResultOn 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.
aStatusIndicates asynchronous operation and on completion contains an error code: see the system-wide error codes.
Capability
Dependenton the type of connection so deferred to PRT

GetByAddress ( const TSockAddr &, TNameEntry & )

IMPORT_C TIntGetByAddress(const TSockAddr &anAddr,
TNameEntry &aResult
)

Get host by address (as get by name)

Gets the name of a host from its address

Parameters
anAddrThe address to use
aResultReturns 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.
Return Value
KErrNone if successful otherwise another of the system-wide error codes.
Capability
Dependenton the type of connection so deferred to PRT

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

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

Resolves a machine name to a TSockAddress asynchronously.

The server will fill in the supplied TNameEntry.

Parameters
aNameThe name to resolve. The format of the name and any wild-cards supported, along with any separators in hierarchical name systems, are protocol specific
aResultOn 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.
aStatusIndicates asynchronous operation and, on completion, contains an error code: see the system-wide error codes.

GetByName ( const TDesC &, TNameEntry & )

IMPORT_C TIntGetByName(const TDesC &aName,
TNameEntry &aResult
)

Resolves a machine name to a TSockAddress.

The server will fill in the supplied TNameEntry.

Parameters
aNameThe name to resolve. The format of the name and any wild-cards supported, along with any separators in hierarchical name systems, are protocol specific
aResultOn 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.
Return Value
KErrNone if successful otherwise another of the system-wide error codes.
Capability
Dependenton the type of connection so deferred to PRT

GetHostName ( TDes & )

IMPORT_C TIntGetHostName(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.

Parameters
aNameReturns 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.
Return Value
KErrNone if successful otherwise another of the system-wide error codes.
Capability
Dependenton the type of connection so deferred to PRT

GetHostName ( TDes &, TRequestStatus & )

IMPORT_C voidGetHostName(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.

Parameters
aNameReturns 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.
aStatusIndicates asynchronous operation and on completion contains an error code: see the system-wide error codes.
Capability
Dependenton the type of connection so deferred to PRT

Next ( TNameEntry &, TRequestStatus & )

IMPORT_C voidNext(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
aResultReturns the next result of the name resolution.
aStatusIndicates asynchronous operation and on completion contains an error code: see the system-wide error codes.

Next ( TNameEntry & )

IMPORT_C TIntNext(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
aResultReturns the next result of the name resolution.
Return Value
KErrNone if successful otherwise another of the system-wide error codes.

Open ( RSocketServ &, TUint, TUint )

IMPORT_C TIntOpen(RSocketServ &aSocketServer,
TUintanAddrFamily,
TUintaProtocol
)

Initialises a name resolution service provided by a particular protocol.

This must be called before other object functions are used.

Parameters
aSocketServerThe socket server session
anAddrFamilyA constant identifying the protocol family
aProtocolA constant that identifies the protocol that provides the name resolution service
Return Value
KErrNone if successful otherwise another of the system-wide error codes.

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

IMPORT_C TIntOpen(RSocketServ &aSocketServer,
TUintanAddrFamily,
TUintaProtocol,
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
anAddrFamilyA constant identifying the protocol family.
aProtocolA constant that identifies the protocol that provides the name resolution service.
aConnectionExisting RConnection whose interface this Host Resolver will be associated with.
Return Value
KErrNone if successful otherwise another of the system-wide error codes.

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

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

Protocol - independent query. Asynchronous version.

Parameters
aQuerycontains query data. The concrete type of the data depends on protocol. e.g. for tcpip it will imply DNS query.
aResultDescriptor that will receive data. The concrete meaning of this data depends on protocol.
aStatusindicates asynchronous operation, on completion contains a system-wide error code
Capability
Dependenton the type of connection so deferred to PRT

Query ( const TDesC8 &, TDes8 & )

IMPORT_C TIntQuery(const TDesC8 &aQuery,
TDes8 &aResult
)

Protocol - independent query. Synchronous version.

Parameters
aQuerycontains query data. The concrete type of the data depends on protocol. e.g. for tcpip it will imply DNS query.
aResultDescriptor that will receive data. The concrete meaning of this data depends on protocol.
Return Value
system-wide error code.
Capability
Dependenton the type of connection so deferred to PRT

QueryGetNext ( TDes8 &, TRequestStatus & )

IMPORT_C voidQueryGetNext(TDes8 &aResult,
TRequestStatus &aStatus
)

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

Parameters
aResultDescriptor that will receive data. The concrete meaning of this data depends on protocol.
aStatusindicates 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 TIntQueryGetNext(TDes8 &aResult)

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

Parameters
aResultDescriptor that will receive data. The concrete meaning of this data depends on protocol.
Return Value
system-wide error code. In particular KErrNotFound means that there is no more information from resolver.

SetHostName ( const TDesC & )

IMPORT_C TIntSetHostName(const TDesC &aName)
Sets the name of the local host.
Parameters
aNameThe local host name.
Return Value
KErrNone if successful, otherwise another of the system-wide error codes.
Capability
NetworkControlService restricting and stored at protocol level

SetOpt ( TUint, TUint, const TDesC8 & )

IMPORT_C TIntSetOpt(TUintanOptionName,
TUintanOptionLevel,
const TDesC8 &anOption =  TPtrC8(0, 0)
)