SFBAddrInfo

Wrapper Class for the IAddrInfo interface.

#include <SFBAddrInfo.h.hpp>

class SFBAddrInfo : public SFBQuery;

SFMTYPEDEFWRAPPER(SFBAddrInfo)

Inheritance diagram

Version

BREW 2.0	BREW 2.1	BREW 3.1	BREW 4.0
X	X	O	O

Reference

BREW API IAddrInfo

Member

Public Functions
`SFCError`	GetResult( `SInt32Ptr` status , `SInt32Ptr` number , `SInt32Ptr` maxsize ) Retrieve the query result, after the resolving transaction completes.
`SFCError`	GetResultAddr( `SInt32` index , `AEEAddrInfo *` addrinfo , `SInt32Ptr` size ) Retrieve a specific address information element query result, after the resolving transaction has completed.
`SFCError`	GetResultAddr( `SInt32` index , `AEEAddrInfo *` addrinfo , `SIntNPtr` size ) Retrieve a specific address information element query result, after the resolving transaction has completed.
static `SFBAddrInfoSmp`	NewInstance( `SFCErrorPtr` exception = null ) Create a new SFBAddrInfo instance.
static `SFBAddrInfoSmp`	NewInstance( `AEECLSID` id , `SFCErrorPtr` exception = null ) Create a new SFBAddrInfo instance.
`SFCError`	SelectNetwork( `SInt32` network ) This function selects a specific data network.
`SFCError`	StartQuery( `ACharConstPtr` node , `ACharConstPtr` server , `AEEAddrInfo const *` hints , `SFXCallbackPtr` callback ) Set the resolver query information and start it.
`SFCError`	StartQuery( `SFXAnsiStringConstRef` node , `SFXAnsiStringConstRef` server , `AEEAddrInfo const *` hints , `SFXCallbackPtr` callback ) Set the resolver query information and start it.
`SFCError`	QueryInterface( `AEECLSID` clsid , `VoidHandle` handle ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`SFCError`	QueryInterface( `AEECLSID` clsid , `SFBBaseSmpPtr` handle ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`SFBBaseSmp`	QueryInterface( `AEECLSID` clsid ) (inherits from SFBQuery) Ask an object for another API contract from the object in question.
`Void`	Self( `AEECLSID` clsidReq , `SFBQuerySmpPtr` clone , `AEECLSID` clsidImp ) (inherits from SFBQuery) Helper macro for those implementing an object with a single interface.
`SFBQuerySmp`	Self( `AEECLSID` clsidReq , `AEECLSID` clsidImp ) (inherits from SFBQuery) Helper macro for those implementing an object with a single interface.

Protected Functions
static `SFBBaseSmp`	FactoryByCreate( `AEECLSID` id , `SFCErrorPtr` exception = null ) (inherits from SFBBase) Create the instance for the specified ClassID's interface.
static `SFBBaseSmp`	FactoryByQuery( `SFBQuerySmpConstRef` query , `AEECLSID` id , `SFCErrorPtr` exception = null ) (inherits from SFBBase) Create the instance for the specified ClassID's interface using the SFBQuery instance.

SFBAddrInfo::GetResult

Retrieve the query result, after the resolving transaction completes.

[ public ]
SFCError GetResult(
    SInt32Ptr status    // The query result status
    SInt32Ptr number    // The number of address information elements generated as a result of the query
    SInt32Ptr maxsize   // The size of the largest address information element generated as a result of the query
);

Argument

status

AEE_SUCCESS: The name was successfully resolved.
AEE_NET_ETIMEDOUT: Request timed out.
AEE_NET_GENERAL_FAILURE: A non-recoverable error occurred when attempting to resolve the name.
AEE_NET_ENOMEM: There was a memory allocation failure.
AEE_NET_EAI_BADREQUEST: request parameters are in error.
AEE_NET_UNKDOMAIN: Unknown host domain name or no address records.
AEE_NET_BADDOMAIN: Improperly formatted host domain name.
AEE_NET_BADRESPONSE: Response did not make sense.

Other error codes are also possible. *

Return value

AEE_SUCCESS: query results were returned.
AEE_EBADSTATE: The object is not in the proper state for the operation. i.e., no query was initiated.
AEE_NET_EFAULT: Invalid buffer or argument has been specified.

Description

On success, returns the resolve query status, the number of returned addresses and the maximum address size.

Reference

BREW API IADDRINFO_GetResult | SFBAddrInfo::GetResultAddr

SFBAddrInfo::GetResultAddr

Retrieve a specific address information element query result, after the resolving transaction has completed.

[ public ]
SFCError GetResultAddr(
    SInt32 index             // zero based index of the address information element to retrieve
    AEEAddrInfo * addrinfo   // pointer to the AEEAddrInfo to be filled in
    SInt32Ptr size           // pointer to the size
);

[ public ]
SFCError GetResultAddr(
    SInt32 index             // zero based index of the address information element to retrieve
    AEEAddrInfo * addrinfo   // pointer to the AEEAddrInfo to be filled in
    SIntNPtr size            // pointer to the size
);

Argument

index: zero based index of the address information element to retrieve.
addrinfo: pointer to the AEEAddrInfo to be filled in. The memory must be pre-allocated by the client
size: On input: pointer to the size (in bytes) of pai, which needs to be large enough to accommodate the address information element including the address itself. On output: updated with the actual size of the address information element, including the address itself.

Return value

AEE_SUCCESS: query results were returned.
AEE_EBADSTATE: The object is not in the proper state for the operation. i.e., no query was initiated
AEE_NET_EFAULT: Invalid buffer or argument has been specified.

Description

In order to get the size of an address information element, use zero *pnAddrInfoBytes.

Reference

BREW API IADDRINFO_GetResultAddr | SFBAddrInfo::GetResult

SFBAddrInfo::NewInstance

Create a new SFBAddrInfo instance.

[ public, static ]
SFBAddrInfoSmp NewInstance(
    SFCErrorPtr exception = null   // Error
);

[ public, static ]
SFBAddrInfoSmp NewInstance(
    AEECLSID id                    // Class ID
    SFCErrorPtr exception = null   // Error
);

SFBAddrInfo::SelectNetwork

This function selects a specific data network.

[ public ]
SFCError SelectNetwork(
    SInt32 network   // data network type
);

Return value

AEE_NET_SUCCESS: the data network was selected.
AEE_EBADSTATE: the network is not valid.
AEE_NET_EOPNOTSUPP: the network has already been selected.
AEE_EFAILED: other error.

Description

When an SFBAddrInfo instance is created, no network is selected. If an SFBAddrInfo method that requires a network (StartQuery) is called before SFBAddrInfo::SelectNetwork(), AEE_NETWORK_DEFAULT will be implicitly selected, and the decision of which network to actually use is deferred to lower layers.

Once a network has been selected, either explicitly via SFBAddrInfo::SelectNetwork(), or implicitly as described above, the network may not be changed. To use a different network, a new IAddrInfo instance is required.

Reference

BREW API IADDRINFO_SelectNetwork

SFBAddrInfo::StartQuery

Set the resolver query information and start it.

[ public ]
SFCError StartQuery(
    ACharConstPtr node          // NULL, host name, ip address or "\brewloopback"
    ACharConstPtr server        // NULL or decimal port number string
    AEEAddrInfo const * hints   // some hints for the resolve process 
    SFXCallbackPtr callback     //  user supplied callback that will be resumed upon completion - results will be available only then
);

[ public ]
SFCError StartQuery(
    SFXAnsiStringConstRef node     // NULL, host name, ip address or "\brewloopback"
    SFXAnsiStringConstRef server   // NULL or decimal port number string 
    AEEAddrInfo const * hints      // some hints for the resolve process 
    SFXCallbackPtr callback        //  user supplied callback that will be resumed upon completion - results will be available only then
);

Argument

node: NULL, host name, ip address or "\brewloopback"
server: NULL or decimal port number string
hints: some hints for the resolve process
callback: user supplied callback that will be resumed upon completion - results will be available only then. if NULL then starts a synchronous query: A synchronous query only returns immediately available results (no network access) and cached results (if an address cache exists). If StartQuery() returns SUCCESS, results are immediately available. if an address needs to be resolved and is not found in the cache

Return value

AEE_SUCCESS: The query information was set.
AEE_EBADSTATE: The object is not in the proper state for the operation. i.e., StartQuery cannot be called again after a transaction was initiated.
AEE_NET_EAI_BADFLAGS: dwFlags in paiHints had an invalid value.
AEE_NET_GENERAL_FAILURE: A non-recoverable error occurred when processing the parameters.
AEE_NET_EAFNOSUPPORT: The address family was not recognized.
AEE_NET_ENOMEM: There was a memory allocation failure.
AEE_NET_EAI_BADREQUEST: request parameters are in error, i.e., neither szNodeName nor szServName were supplied (at least one of these must be supplied).
AEE_NET_ESOCKNOSUPPORT: The intended socket type was not recognized.
AEE_NET_EAI_UNSUPPFLAGS: dwFlags in paiHints had an unsupported value.
AEE_NET_UNKDOMAIN: for an synchronous query, the address needs to be resolved but was not found in the address cache.

Other errors might be returned; the caller should verify that SFBAddrInfo::StartQuery() succeeded.

Description

See RFC 3493 section 6.1 for more details. A query can not be started more then once!

Reference

BREW API IADDRINFO_StartQuery