Class RHostResolver

class RHostResolver : public RSubSessionBase;

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.

Derivation

• RSubSessionBase - Client-side handle to a sub-session.

• RHostResolver - Provides an interface to host name resolution services, such as DNS, that may be...

Members

Defined in RHostResolver:

• Cancel()Cancels any outstanding asynchronous calls, which will return with error code KE...
• Close()Closes a name resolution service. If a service has been opened using RHostResolv...
• GetByAddress(const TSockAddr &,TNameEntry &)Get host by address (as get by name)
• GetByAddress(const TSockAddr &,TNameEntry &,TRequestStatus &)Get host by address (as get by name)
• GetByName(const TDesC &,TNameEntry &)Resolves a machine name to a TSockAddress.
• GetByName(const TDesC &,TNameEntry &,TRequestStatus &)Resolves a machine name to a TSockAddress asynchronously.
• GetHostName(TDes &)Gets the name of the local host.
• GetHostName(TDes &,TRequestStatus &)Gets the name of the local host asynchronously.
• Next(TNameEntry &)Get the next response if there is more than one response for a given host name (...
• Next(TNameEntry &,TRequestStatus &)Get the next response if there is more than one response for a given host name (...
• Open(RSocketServ &,TUint,TUint)Initialises a name resolution service provided by a particular protocol.
• Open(RSocketServ &,TUint,TUint,RConnection &)Initialises a name resolution service provided by a particular protocol, and ass...
• Query(const TDesC8 &,TDes8 &)Protocol - independent query. Synchronous version.
• Query(const TDesC8 &,TDes8 &,TRequestStatus &)Protocol - independent query. Asynchronous version.
• QueryGetNext(TDes8 &)Get the next query result. For some queries there can be more than one results. ...
• QueryGetNext(TDes8 &,TRequestStatus &)Get the next query result. For some queries there can be more than one results. ...
• SetHostName(const TDesC &)Sets the name of the local host.

Inherited from RSubSessionBase:

• CloseSubSession(TInt)Closes the sub-session.
• CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)Creates a new sub-session within an existing session. The new sub-session takes ...
• CreateSubSession(const RSessionBase &,TInt)Creates a new sub-session within an existing session.
• CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)Creates a new sub-session within an existing session.
• Send(TInt)constSends a blind message to the server - no reply is expected.
• Send(TInt,const TIpcArgs &)constSends a blind message to the server - no reply is expected.
• SendReceive(TInt)constSends a message to the server and waits synchronously for a reply.
• SendReceive(TInt,TRequestStatus &)constSends a message to the server and waits asynchronously for the reply.
• SendReceive(TInt,const TIpcArgs &)constSends a message to the server and waits synchronously for a reply.
• SendReceive(TInt,const TIpcArgs &,TRequestStatus &)constSends a message to the server and waits asynchronously for the reply.
• Session()constReturns a copy of the session associated with this sub-session.
• SubSessionHandle()constGets the sub-session handle number.

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

Description

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

Return value

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

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

Description

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.

Return value

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

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

Description

Resolves a machine name to a TSockAddress asynchronously.

The server will fill in the supplied TNameEntry.

Parameters

const TDesC16 &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 TPckgBuf &aResult On return, the result of the name resolution. If more than one result is allowed by the protocol, the client can call RHostResolver::Next(TNameEntry &,TRequestStatus &) to find any further results. TRequestStatus &aStatus Indicates asynchronous operation and, on completion, contains an error code: see the system-wide error codes.

Capability:

Dependent

on the type of connection so deferred to PRT

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

Description

Resolves a machine name to a TSockAddress.

The server will fill in the supplied TNameEntry.

Parameters

const TDesC16 &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 TPckgBuf &aResult On return, the result of the name resolution. If more than one result is allowed by the protocol, the client can call RHostResolver::Next(TNameEntry &,TRequestStatus &) to find any further results.

Return value

TInt

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

Description

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, RHostResolver::GetByName(const TDesC &,TNameEntry &,TRequestStatus &) and RHostResolver::GetByAddress(const TSockAddr &,TNameEntry &,TRequestStatus &) may find more than one answer, for example if aliases are allowed.

Parameters

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

IMPORT_C TInt Next(TNameEntry &aResult);

Description

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, RHostResolver::GetByName(const TDesC &,TNameEntry &,TRequestStatus &) and RHostResolver::GetByAddress(const TSockAddr &,TNameEntry &,TRequestStatus &) may find more than one answer, for example if aliases are allowed.

Parameters

TPckgBuf &aResult Returns the next result of the name resolution.

Return value

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

Capability:

Dependent

on the type of connection so deferred to PRT

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

Description

Get host by address (as get by name)

Gets the name of a host from its address asynchronously

Parameters

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

Capability:

Dependent

on the type of connection so deferred to PRT

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

Description

Get host by address (as get by name)

Gets the name of a host from its address

Parameters

const TSockAddr &anAddr The address to use TPckgBuf &aResult Returns the result of the query. If more than one result is allowed by the protocol, the client can call RHostResolver::Next(TNameEntry &,TRequestStatus &) to find any further results.

Return value

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

Capability:

Dependent

on the type of connection so deferred to PRT

IMPORT_C TInt GetHostName(TDes &aName);

Description

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 RHostResolver::SetHostName(const TDesC &) must have been made.

Parameters

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

Return value

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

Capability:

Dependent

on the type of connection so deferred to PRT

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

Description

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 RHostResolver::SetHostName(const TDesC &) must have been made.

Parameters

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

Capability:

NetworkControl

Service restricting and stored at protocol level

IMPORT_C TInt SetHostName(const TDesC &aName);

Description

Sets the name of the local host.

Parameters

const TDesC16 &aName The local host name.

Return value

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

IMPORT_C void Close();

Description

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

IMPORT_C void Cancel();

Description

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

Capability:

Dependent

on the type of connection so deferred to PRT

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

Description

Protocol - independent query. Asynchronous version.

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

Capability:

Dependent

on the type of connection so deferred to PRT

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

Description

Protocol - independent query. Synchronous version.

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.

Return value

TInt system-wide error code.

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

Description

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.

IMPORT_C TInt QueryGetNext(TDes8 &aResult);

Description

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.

Return value

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