SFXInetAddress

Class for managing a domain name and/or an IP address.

#include <SFXInetAddress.h.hpp>

class SFXInetAddress;

SFMTYPEDEFCLASS(SFXInetAddress)

Inheritance diagram

Collaboration diagram

Description

The SFXInetAddress class provides functions such as managing domain and/or IP address or resolving domain to IP address

	Tip
	To manage port number other than domain and/or IP address, use the `SFXSocketAddress` class.

How to use the SFXInetAddress class

Set a domain with the SFXInetAddress::SFXInetAddress constructor or the SFXInetAddress::Set function.
Resolve the domain with the SFXInetAddress::Resolve function. The callback function notified of result of domain name resolution should specified in the argument of this function.
Domain resolution can be canceled by calling the SFXInetAddress::Cancel function.
After domain name resolution finishes, the callback function registered in Step 2. will be called.
In the callback function, processing after domain name resolution is described.

	Note
	There is no need to resolve domain with the `SFXInetAddress::Resolve` function when an IP address is specified with the `SFXInetAddress::SFXInetAddress` constructor or the `SFXInetAddress::Set` function.

Example 823. Method to resolve domain

class MyClass {
    SFXInetAddress _address;
    Void Function(Void);
    XALLBACK_DECLARE_SFXINETADDRESS(ResolveCallback)
};

Void MyClass::Function(Void)
{
    SFCError error;

    // set domain name
    if ((error = _address.Set("http://www.example.com/test"); == SFERR_NO_ERROR) {

        // resolve domain name(result of domain name resolution will be notified to the ResolveCallback function)
        error = _address.Resolve(XALLBACK_INTERNAL(ResolveCallback));
    }
    if (error != SFERR_NO_ERROR) {

        // if an error occurs, the ResolveCallback function will not be called

        // error handling
        ...
    }
    
}

// callback function notified of result of domain name resolution
XALLBACK_IMPLEMENT_SFXINETADDRESS(MyClass, ResolveCallback, error)
{
     SInt16 i;

     // display domain name on BREW Output window
     TRACE("%s",_address.Get().GetCString());
     
      // repeat number of IP addresses
     for(i = 0 ; i < _address.GetCount() ; i++){

         // display IP address on BREW Output window
         TRACE("%s",_address.GetIP(i).GetCString());  
     }
    
}

Reference

SFXSocketAddress | IP address, domain, port number

Member

Constructor/Destructor
SFXInetAddress( `Void` ) Constructor of the SFXInetAddress class.
SFXInetAddress( `SFXInetAddressConstRef` param ) Constructor of the SFXInetAddress class.
SFXInetAddress( `SFXAnsiStringConstRef` param ) Constructor of the SFXInetAddress class.
SFXInetAddress( `INAddr` inaddr ) Constructor of the SFXInetAddress class.
~SFXInetAddress( `Void` ) Destructor of the SFXInetAddress class.

Public Functions
static `SFXInetAddress`	AnyInetAddress( `Void` ) Get INADDR_ANY of the SFXInetAddress type.
`INAddr`	AsINAddr( `SInt16` index = 0 ) Get the IP address of the INAddr type from this object.
`Void`	Cancel( `Void` ) Cancel to resolve the domain name.
`Void`	Clear( `Void` ) Clear the domain name or IP address setting of this object.
static `SFXInetAddressConstRef`	EmptyInstance( `Void` ) Get an empty address.
`SFXAnsiStringConstRef`	Get( `Void` ) Get the domain name of the SFXAnsiString type from this object.
`SInt16`	GetCount( `Void` ) Get the number of IP addresses from this object.
`SFXAnsiString`	GetIP( `SInt16` index = 0 ) Get the IP address of the SFXAnsiString type from this object.
static `SFXInetAddress`	LocalInetAddress( `Void` ) Get the IP address of the local host or device.
static `SFXInetAddress`	LoopbackInetAddress( `Void` ) Get the loopback address of the SFXInetAddress type.
`SFCError`	Resolve( `CallbackSPP` spp , `VoidPtr` reference ) Resolve the domain name.
`SFCError`	Set( `SFXInetAddressConstRef` param ) Set the specified domain name or IP address to this object.
`SFCError`	Set( `SFXAnsiStringConstRef` param ) Set the specified domain name or IP address to this object.
`SFCError`	Set( `INAddr` inaddr ) Set the specified domain name or IP address to this object.
`SFXInetAddressRef`	operator=( `SFXInetAddressConstRef` param ) Assign the specified address of the SFXInetAddress type.

Types
CallbackSPP Type that represents the callback function.

SFXInetAddress::SFXInetAddress

Constructor of the SFXInetAddress class.

[ public, explicit ]
SFXInetAddress(Void);

[ public ]
SFXInetAddress(
    SFXInetAddressConstRef param   // source SFXInetAddress
);

[ public, explicit ]
SFXInetAddress(
    SFXAnsiStringConstRef param   // domain name
);

[ public, explicit ]
SFXInetAddress(
    INAddr inaddr   // IP Address
);

Description

If a domain name or an IP address is specified in the argument of this constructor, it will be set to this object by calling the SFXInetAddress::Set function internally.

Otherwise, this constructor will do nothing.

Reference

SFXInetAddress::Set

SFXInetAddress::~SFXInetAddress

Destructor of the SFXInetAddress class.

[ public ]
~SFXInetAddress(Void);

Description

This destructor cancels to resolve the domain name by calling the SFXInetAddress::Cancel function internally.

Reference

SFXInetAddress::Cancel

SFXInetAddress::AnyInetAddress

Get INADDR_ANY of the SFXInetAddress type.

[ public, static ]
SFXInetAddress AnyInetAddress(Void);

Return value

INADDR_ANY (AEE_INADDR_ANY: 0.0.0.0) of the SFXInetAddress type

Description

This function gets INADDR_ANY (BREW API AEE_INADDR_ANY) of the SFXInetAddress type.

Note

	Note
In BREW, INADDR_ANY (`BREW API AEE_INADDR_ANY`) is defined as follows: #define AEE_INADDR_ANY ((INAddr) 0) The `BREW API INAddr` type is defined as follows: typedef uint32 INAddr;

In BREW, INADDR_ANY (BREW API AEE_INADDR_ANY) is defined as follows:

#define AEE_INADDR_ANY      ((INAddr) 0)

The BREW API INAddr type is defined as follows:

typedef uint32 INAddr;

Reference

SFXInetAddress::LocalInetAddress | SFXInetAddress::LoopbackInetAddress | BREW API AEE_INADDR_ANY | BREW API INAddr

SFXInetAddress::AsINAddr

Get the IP address of the INAddr type from this object.

[ public, const ]
INAddr AsINAddr(
    SInt16 index = 0   // index
);

Return value

IP address of the BREW API INAddr type

Description

This function gets the IP address of the BREW API INAddr type from this object.

When this object contains a multiple of IP addresses, the IP address can be specified in the index argument. The default index is 0.

The number of IP addresses that this object contains can be obtained by calling the SFXInetAddress::GetCount function.

	Note
	When not an IP address but a domain name is set to this object with the `SFXInetAddress::SFXInetAddress` constructor or the `SFXInetAddress::Set` function, it is necessary to resolve the domain name with the `SFXInetAddress::Resolve` function before this function is called.

Note

	Note
The `BREW API INAddr` type is defined as follows: typedef uint32 INAddr;

The BREW API INAddr type is defined as follows:

typedef uint32 INAddr;

Reference

SFXInetAddress::Cancel

Cancel to resolve the domain name.

[ public ]
Void Cancel(Void);

Description

This function cancels to resolve the domain name.

Concretely, this function cancels the callback function registered with the SFXInetAddress::Resolve function and releases the SFBNetMgr instance that the SFXInetAddress::Resolve function creates internally.

Tip

	Tip
This function is used to cancel to resolve the domain name before the callback function is called after calling the `SFXInetAddress::Resolve` function. This function is called in the `SFXInetAddress::~SFXInetAddress` destructor or `SFXInetAddress::Clear` function.

This function is used to cancel to resolve the domain name before the callback function is called after calling the SFXInetAddress::Resolve function.

This function is called in the SFXInetAddress::~SFXInetAddress destructor or SFXInetAddress::Clear function.

Reference

SFXInetAddress::Resolve | SFXInetAddress::~SFXInetAddress | SFXInetAddress::Clear | SFBNetMgr

SFXInetAddress::Clear

Clear the domain name or IP address setting of this object.

[ public ]
Void Clear(Void);

Description

This function cancels the domain name resolution of the SFXInetAddress::Resolve function by calling the SFXInetAddress::Cancel function internally and clears the domain name or IP address setting of this object set with the SFXInetAddress::Set function or the SFXInetAddress::SFXInetAddress constructor.

Reference

SFXInetAddress::Set | SFXInetAddress::SFXInetAddress | SFXInetAddress::Cancel | SFXInetAddress::Resolve

SFXInetAddress::EmptyInstance

Get an empty address.

[ public, static ]
SFXInetAddressConstRef EmptyInstance(Void);

Return value

Empty address of the SFXInetAddress type

Description

This function gets an empty address of the SFXInetAddress type.

	Tip
	This function is used to return an empty address as the return value of a function.

SFXInetAddress::Get

Get the domain name of the SFXAnsiString type from this object.

[ public, const ]
SFXAnsiStringConstRef Get(Void);

Return value

Domain name of the SFXAnsiString type

Description

This function gets the domain name of the SFXAnsiString type from this object.

	Note
	If an IP address of the `BREW API INAddr` type is set with the `SFXInetAddress::SFXInetAddress` constructor or the `SFXInetAddress::Set` function, it will be returned in the "nnn.nnn.nnn.nnn" (nnn: number) format of the `SFXAnsiString` type as the domain name.

Reference

SFXInetAddress::GetCount

Get the number of IP addresses from this object.

[ public, const ]
SInt16 GetCount(Void);

Return value

Number of IP addresses of this object

Description

This function gets the number of IP addresses set to this object.

	Note
	When not an IP address but a domain name is set to this object with the `SFXInetAddress::SFXInetAddress` constructor or the `SFXInetAddress::Set` function, it is necessary to resolve the domain name with the `SFXInetAddress::Resolve` function before this function is called.

Reference

SFXInetAddress::Resolve | SFXInetAddress::AsINAddr | SFXInetAddress::GetIP

SFXInetAddress::GetIP

Get the IP address of the SFXAnsiString type from this object.

[ public, const ]
SFXAnsiString GetIP(
    SInt16 index = 0   // index
);

Return value

IP address in the "nnn.nnn.nnn.nnn"(nnn: number) format of the SFXAnsiString type from this object

Description

This function gets the IP address in the "nnn.nnn.nnn.nnn"(nnn: number) format of the SFXAnsiString type from this object.

When this object contains a multiple of IP addresses, the IP address can be specified in the index argument. The default index is 0.

The number of IP addresses that this object contains can be obtained by calling the SFXInetAddress::GetCount function.

	Note
	When not an IP address but a domain name is set to this object with the `SFXInetAddress::SFXInetAddress` constructor or the `SFXInetAddress::Set` function, it is necessary to resolve the domain name with the `SFXInetAddress::Resolve` function before this function is called.

Reference

SFXInetAddress::LocalInetAddress

Get the IP address of the local host or device.

[ public, static ]
SFXInetAddress LocalInetAddress(Void);

Return value

IP address of the local host or device of the SFXInetAddress type

Description

This function gets the IP address of the local host or device of the SFXInetAddress type.

	Note
	This function internally calls the `SFBNetMgr::GetMyIPAddr` function.

Reference

SFXInetAddress::AnyInetAddress | SFXInetAddress::LoopbackInetAddress | SFBNetMgr::GetMyIPAddr | BREW API INETMGR_GetMyIPAddr

SFXInetAddress::LoopbackInetAddress

Get the loopback address of the SFXInetAddress type.

[ public, static ]
SFXInetAddress LoopbackInetAddress(Void);

Return value

Loopback address (AEE_BREW_LOOPBACK: 127.0.0.69) of the SFXInetAddress type

Description

This function gets the loopback address of BREW API AEE_BREW_LOOPBACK that is converted into the SFXInetAddress type.

Note

	Note
`BREW API AEE_BREW_LOOPBACK` is defined as follows: #define AEE_BREW_LOOPBACK (0x7f000045L)

BREW API AEE_BREW_LOOPBACK is defined as follows:

#define AEE_BREW_LOOPBACK   (0x7f000045L)

	Tip
	This function is valid in BREW 2.1 or above.

Reference

SFXInetAddress::AnyInetAddress | SFXInetAddress::LocalInetAddress | BREW API AEE_BREW_LOOPBACK

SFXInetAddress::Resolve

Resolve the domain name.

[ public ]
SFCError Resolve(
    CallbackSPP spp     // callback function
    VoidPtr reference   // data passed to callback function
);

Return value

If succeeds: SFERR_NO_ERROR
If this function is called during resolving the domain name: SFERR_INVALID_STATE
If the domain name is not set: SFERR_INVALID_STATE
If failed to create the SFBNetMgr instance: SFERR_FAILED

Description

This function resolves the domain name included in the address set with the SFXInetAddress::SFXInetAddress constructor or the SFXInetAddress::Set function.

The resolved IP addresses can be obtained with the SFXInetAddress::GetIP / SFXInetAddress::AsINAddr function.

As a result of domain name resolution, a domain name may be converted into a multiple of IP addresses. In such a case, by specifying the index value in the argument of the SFXInetAddress::GetIP / SFXInetAddress::AsINAddr function, any IP address can be obtained. The total number of IP addresses can be obtained with the SFXInetAddress::GetCount function.

When the domain name resolution completes, the callback function specified in the argument will be called. However, if an error occurs in this function, it will not be called.

The domain name resolution can be canceled by calling the SFXInetAddress::Cancel function before the callback function is called.

	First argument of the callback function
	This function internally calls the `BREW API INETMGR_GetHostByName` function. The following return value(error) of the `BREW API INETMGR_GetHostByName` function will be passed to the first argument of the callback function: AEE_NET_BADDOMAIN: Host name is malformed; not a valid host name. AEE_NET_UNKDOMAIN: Unknown host, or one without IP addresses. AEE_NET_ETIMEDOUT: No response was seen within the maximum time limit. EUNSUPPORTED: DNS servers do not need to be configured on the device for it to work properly, otherwise EUNSUPPORTED is returned. AEE_NET_GENERAL_FAILURE: When there is an allocation failure. AEE_NET_EOPNOTSUPP: DNS Look up Not Supported.

Note

	Note
If an IP address is set or a domain name is set in the "nnn.nnn.nnn.nnn"(nnn: number) format, there is no need to resolve the domain name by calling the `SFXInetAddress::Resolve` function. When socket communication is performed using SophiaFramework UNIVERSE, there is no need to resolve the domain name by calling the `SFXInetAddress::Resolve` function since the domain name will be automatically resolved only by passing the address(domain name and port number) of the `SFXSocketAddress` type.

If an IP address is set or a domain name is set in the "nnn.nnn.nnn.nnn"(nnn: number) format, there is no need to resolve the domain name by calling the SFXInetAddress::Resolve function.

When socket communication is performed using SophiaFramework UNIVERSE, there is no need to resolve the domain name by calling the SFXInetAddress::Resolve function since the domain name will be automatically resolved only by passing the address(domain name and port number) of the SFXSocketAddress type.

Example

class MyClass {
    SFXInetAddress _address;
    Void Function(Void);
    XALLBACK_DECLARE_SFXINETADDRESS(ResolveCallback)
};

Void MyClass::Function(Void)
{
    SFCError error;

    // set domain name
    if ((error = _address.Set("http://www.example.com/test"); == SFERR_NO_ERROR) {

        // resolve domain name(result of domain name resolution will be notified to the ResolveCallback function)
        error = _address.Resolve(XALLBACK_INTERNAL(ResolveCallback));
    }
    if (error != SFERR_NO_ERROR) {

        // if an error occurs, the ResolveCallback function will not be called

        // error handling
        ...
    }
    
}

// callback function notified of result of domain name resolution
XALLBACK_IMPLEMENT_SFXINETADDRESS(MyClass, ResolveCallback, error)
{
     SInt16 i;

     // display domain name on BREW Output window
     TRACE("%s",_address.Get().GetCString());
     
      // repeat number of IP addresses
     for(i = 0 ; i < _address.GetCount() ; i++){

         // display IP address on BREW Output window
         TRACE("%s",_address.GetIP(i).GetCString());  
     }
    
}

Reference

SFXInetAddress::Set

Set the specified domain name or IP address to this object.

[ public ]
SFCError Set(
    SFXInetAddressConstRef param   // source SFXInetAddress
);

[ public ]
SFCError Set(
    SFXAnsiStringConstRef param   // domain name
);

[ public ]
SFCError Set(
    INAddr inaddr   // IP Address
);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMORY

Description

This function sets the specified domain name or IP address to this object.

The IP address or domain name set to this object with this function can be obtained by calling the SFXInetAddress::Get function.

If the argument is of the SFXAnsiString type, a string in the following format can be specified. And only the <domain name> will be extracted from this string and set to this object.

<protocol> :// <domain name> : <port> / <path>  

or

<account> @ <domain>

When <domain name> is in the "nnn.nnn.nnn.nnn" (nnn: number) format or the argument is an IP address of the BREW API INAddr type, there is no need to call the SFXInetAddress::Resolve function in order to get the IP address. In this case, the IP address can be obtained by calling the SFXInetAddress::AsINAddr / SFXInetAddress::GetIP function without any domain name resolution.

Caution

	Caution
This function internally calls the `SFXInetAddress::Cancel` function first. Therefore, if this function is called during the domain name resolution( from calling the `SFXInetAddress::Resolve` function until the result is notified to the callback function), the domain name resolution will be canceled.

This function internally calls the SFXInetAddress::Cancel function first.

Therefore, if this function is called during the domain name resolution( from calling the SFXInetAddress::Resolve function until the result is notified to the callback function), the domain name resolution will be canceled.

Example

SFXInetAddress address;
SFXAnsiString  domain;

address.Set("http://www.example.com:80/test");

domain = address.Get(); // domain: "www.example.com"

SFXInetAddress address;
INAddr         ipaddress_INAddr;
SFXAnsiString  ipaddress_SFXAnsiString;

address.Set("127.0.0.1/test");

ipaddress_INAddr        = address.AsINAddr(); // get IP address("127.0.0.1") of the INAddr type 
ipaddress_SFXAnsiString = address.GetIP();    // get IP address("127.0.0.1") of the SFXAnsiString type

Reference

SFXInetAddress::operator=

Assign the specified address of the SFXInetAddress type.

[ public ]
SFXInetAddressRef operator=(
    SFXInetAddressConstRef param   // source SFXInetAddress
);

Description

This operator assigns the specified address of the SFXInetAddress type.

Reference

SFXInetAddress::Set

SFXInetAddress::CallbackSPP

Type that represents the callback function.

typedef Void(* SFXInetAddress::CallbackSPP)(SFCError error, VoidPtr reference)

Description

The SFXInetAddress::CallbackSPP function is the prototype for the callback function used in the SFXInetAddress class. The result of communication processing is notified to the callback function.

The error code is passed to the 1st argument, the parameter for the callback function is passed to the 2nd argument.

Reference

SFXInetAddress::Resolve