Description

The SFXUDPSocket class provides the functions to implement both of the UDP client and the UDP sever.

In this class, data cannot be sent nor received using the stream. Instead, data can be sent and received with the SFXUDPSocket::Send / SFXUDPSocket::Receive function.

	Note
	The SFXUDPSocket class encapsulates BREW API ISocket interface to provide high level functions for the UDP socket communication.

How to implement the UDP client

The UDP client can be implemented by taking the following procedures with the SFXUDPSocket class.

How to implement the UDP server

The UDP server can be implemented by taking the following procedures with the SFXUDPSocket class.

	Note
	The UDP sever can send data to another UDP server as the UDP client.

// The _socket variable is defined as class member variable since used in the callback function
class MyClass {
private:
    SFXUDPSocket _socket;

public:
    Void Start(Void);

    // callback functions
    XALLBACK_DECLARE_SFXUDPSOCKET(OnBind)
    XALLBACK_DECLARE_SFXUDPSOCKET(OnSend)
    XALLBACK_DECLARE_SFXUDPSOCKET(OnReceive)
};

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

    // open UDP socket
    if ((error = _socket.Open()) == SFERR_NO_ERROR) {

        // bind local IP address and port number to UDP socket
        OnBind(SFERR_NO_ERROR);
    
    }
    return;
}

// callback function notified that binding is ready to be performed
XALLBACK_IMPLEMENT_SFXUDPSOCKET(MyClass, OnBind, error)
{
    SFXSocketAddress address(SFXInetAddress::LoopbackInetAddress(), 1024);

    // check whether or not an error occurs
    if (error == SFERR_NO_ERROR) {

        error = _socket.Bind(address);

        switch (error) {
            case SFERR_NO_ERROR:

                // send data asynchronously
                OnSend(SFERR_NO_ERROR);
                break;
            case AEE_NET_WOULDBLOCK:

                // schedule to perform binding: register the OnBind callback function
                // * the OnBind callback function will be called by BREW AEE when binding is ready to be performed
                _socket.ScheduleBind(XALLBACK_INTERNAL(OnBind));
                break;
        }
    }
    return;
}

// callback function notified that data is ready to be sent
XALLBACK_IMPLEMENT_SFXUDPSOCKET(MyClass, OnSend, error)
{
    static ACharConst data[] = "udp!";
    SFXSocketAddress address(SFXInetAddress::LoopbackInetAddress(), 1024);
    UInt32 size;

    // check error
    if (error == SFERR_NO_ERROR) {
        size = sizeof(data) - 1;

        // send data
        error = _socket.Send(address, data, &size);

        switch (error) {
            case SFERR_NO_ERROR:

                // check whether data of specified size is written or not
                // SFXUDPSocket::Send function may not send data of specified size at a time
                // here for simple explanation, display error message
                if (size == sizeof(data) - 1) {

                    // receive data asynchronously
                    OnReceive(SFERR_NO_ERROR);
                }
                else {
                    TRACE("...failed to send ...");
                }
                break;
            case AEE_NET_WOULDBLOCK:
                // if sending data is blocked

                // schedule to send data: register the OnSend callback function
                // * the OnSend callback function will be called by BREW AEE when data is ready to be sent
                _socket.ScheduleSend(XALLBACK_INTERNAL(OnSend));
                break;
        }
    }
    return;
}

// callback function notified that data is ready to be received
XALLBACK_IMPLEMENT_SFXUDPSOCKET(MyClass, OnReceive, error)
{
    SFXSocketAddress socket;
    SFXBuffer buffer;
    UInt32 size;

    // check error
    if (error == SFERR_NO_ERROR) {
        buffer.SetSize(4);

        size = static_cast<UInt16>(buffer.GetSize());

        // receive data
        switch (_socket.Receive(&socket, buffer.GetBuffer(), &size)) {
            case SFERR_NO_ERROR:

                // check whether data of specified size is read or not
                // SFXUDPSocket::Receive function may not receive data of specified size at a time
                // here for simple explanation, display error message
                if (size == buffer.GetSize()) {

                    // display received data
                    buffer.SetSize(buffer.GetSize() + 1);
                    buffer[buffer.GetSize() - 1] = '\0';
                    TRACE(":%s", SFXAnsiString(buffer).GetCString());

                    // close socket
                    _socket.Close();
                }
                else {
                    TRACE("...failed to receive...");
                }
                break;
            case AEE_NET_WOULDBLOCK:
                // if receiving data is blocked

                // schedule to receive data: register the OnReceive callback function
                // * the OnReceive callback function will be called by BREW AEE when data is ready to be received
                _socket.ScheduleReceive(XALLBACK_INTERNAL(OnReceive));
                break;
        }
    }
    return;
}

Reference

SFXTCPSocket | SFXSSLSocket | SFXSocketAddress | BREW API ISocket | UDP Socket Communication

Member

Description

This constructor does nothing.

Description

This destructor calls the SFXUDPSocket::Close function.

	Note
	Registered callback functions will be canceled.

Reference

SFXUDPSocket::Close

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Return value

Description

This function binds(or binds the specified local IP address and port number to this UDP socket).

In case of loopback communication within the device only, specify SFXInetAddress::LoopbackInetAddress() as the local IP address. Otherwise, i.e., when communicating with an external server, specify SFXInetAddress::AnyInetAddress(). For the limitation on BREW SDK, values other than these two are not supported.

The IP address and the port number bound to this UDP socket with this function is the source when sending data with the SFXUDPSocket::Send function (return value that the SFXUDPSocket::Receive function will receive via the address argument).

* If this function returns AEE_NET_WOULDBLOCK, it will be necessary to register a callback function with the SFXUDPSocket::ScheduleBind function where binding will be performed with this function.

	Note
	In the UDP socket communication, it is necessary to bind the local IP address and port number to the UDP socket with this function before receiving data with the SFXUDPSocket::Receive function. When sending data with the SFXUDPSocket::Send function you don't necessarily have to bind. If binding is omitted, default port number will be bound to this UDP socket.

	Note
	This function internally calls the SFBSocket::Bind function.

	Prerequisite
	This socket needs to be opened with the SFXUDPSocket::Open function before this function is called.

Reference

SFXUDPSocket::Open | SFXUDPSocket::ScheduleBind | SFXInetAddress::LoopbackInetAddress | SFXInetAddress::AnyInetAddress | SFXUDPSocket::Send | SFXUDPSocket::Receive | SFXSocketAddress | SFBSocket::Bind | BREW API ISOCKET_Bind | BREW API AEE_BREW_LOOPBACK | BREW API AEE_INADDR_LOOPBACK | BREW API AEE_INADDR_ANY

Description

This function cancels various operations on this UDP socket.

Concretely, the registered callback function for each operation will be canceled and the status will be returned to before that operation is performed.

The operations to be canceled and its details are in the following table:

	Note
	This function is called in the SFXUDPSocket::Close function.

Reference

SFXUDPSocket::Open | SFXUDPSocket::ScheduleBind | SFXUDPSocket::ScheduleReceive | SFXUDPSocket::ScheduleSend | SFXUDPSocket::Close

Description

This function closes this UDP socket.

Concretely, this function calls the SFXUDPSocket::Cancel function and releases the SFBNetMgr and SFBSocket instances that this UDP socket internally manages.

	Note
	The registered callback functions will be canceled.

	Note
	This function is called in the SFXUDPSocket::~SFXUDPSocket destructor.

	Tip
	When suspending, resources should be released by calling this function.

Reference

SFXUDPSocket::Open | SFXUDPSocket::Cancel | SFXUDPSocket::~SFXUDPSocket | SFBNetMgr | SFBSocket | BREW API INetMgr | BREW API ISocket

Return value

Description

This function gets the local IP address and port number of this UDP socket.

Always, the value set with the SFXUDPSocket::Bind function will be return.

	Tip
	The actual physical IP address can be also obtained by calling the SFXInetAddress::LocalInetAddress function.

	Prerequisite
	To get the local IP address and port number, this socket needs to be bound with the SFXUDPSocket::Bind function.

Reference

SFXUDPSocket::Bind | SFXInetAddress::LocalInetAddress | SFXSocketAddress | BREW API ISOCKET_GetLastError

Return value

SFBNetMgr instance managed internally by this socket.

Description

This function gets the SFBNetMgr instance managed internally by this socket.

Reference

SFBNetMgr | BREW API INetMgr

Return value

SFBSocket instance managed internally by this socket.

Description

This function gets the SFBSocket instance managed internally by this socket.

Reference

SFBSocket | BREW API ISocket

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Return value

Description

This function opens (or initializes) this this UDP socket.

Concretely, this function creates the SFBNetMgr instance and calls the BREW API INETMGR_OpenSocket function to create the SFBSocket instance of the AEE_SOCK_DGRAM type. These instances are internally managed by this UDP socket.

The SFBNetMgr / SFBSocket instance can be obtained with the SFXUDPSocket::GetSFBNetMgr / SFXUDPSocket::GetSFBSocket function. More detailed setting can be realized by using these instances.

	Linger time(waiting time for connecting a network)
	The linger time(waiting time for connecting a network) set up by the BREW API INETMGR_SetLinger function, can be specified by the linger argument of this function. Default value of this argument is -1. At this time the linger time is not set up. For more details on the linger time settings, refer to BREW API INETMGR_SetLinger.

	Tip
	If the SFXUDPSocket::Close function is called, this UDP socket will be closed.

Reference

SFXUDPSocket::Close | SFXUDPSocket::GetSFBNetMgr | SFXUDPSocket::GetSFBSocket | SFBNetMgr | SFBSocket | BREW API INetMgr | BREW API ISocket | BREW API INETMGR_OpenSocket | BREW API INETMGR_SetLinger

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Argument

Return value

Description

This function receives data from this UDP socket without input stream.

* If this function returns AEE_NET_WOULDBLOCK, it will be necessary to register a callback function with the SFXUDPSocket::ScheduleReceive function where data will be received with this function.

	Note
	This function internally calls the SFBSocket::RecvFrom function.

	Prerequisite
	This socket needs to be bound with the SFXUDPSocket::Bind function before this function is called.

Reference

SFXUDPSocket::ScheduleReceive | SFXUDPSocket::Bind | SFXSocketAddress | SFBSocket::RecvFrom | BREW API ISOCKET_RecvFrom

Return value

Description

This function schedules to bind the local IP address and port number to this UDP socket.

Concretely, this function registers the callback function that will bind the local IP address and port number to this UDP socket with the SFXUDPSocket::Bind function. The registered callback function will be called by BREW AEE when it is possible to bind.

The status of this socket is "under scheduling to bind" until the callback function is called. And after the callback function is called, it will become the status before calling this function, i.e., "this socket is opened".

If you call the SFXUDPSocket::Cancel function before the callback function is called, binding will be canceled and the status will be returned to the status before calling this function, i.e., "this socket is opened".

*1. If the SFXUDPSocket::Bind function returns AEE_NET_WOULDBLOCK, it will be necessary to register a callback function with this function where binding will be performed with the SFXUDPSocket::Bind function.

*2. If this function returns the value other than SFERR_NO_ERROR, the specified callback function will not be called.

	Note
	This function internally calls the SFBSocket::Writeable function.

	Prerequisite
	Before this function is called, this socket needs to be opened with the SFXUDPSocket::Open function. If binding has already been scheduled, the SFERR_INVALID_STATE error will be returned too.

Reference

SFXUDPSocket::Bind | SFXUDPSocket::Cancel | SFXUDPSocket::Open | SFBSocket::Writeable | SFXStorage::CallbackSPP | BREW API ISOCKET_Writeable

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Reference

SFXStorage::CallbackSPP

Return value

Description

This function schedules to receive data from this UDP socket without input stream.

Concretely, this function registers the callback function that will receive data with the SFXUDPSocket::Receive function. The registered callback function will be called by BREW AEE when it is possible to receive data.

The status of this socket is "under scheduling to receive data" until the callback function is called. And after the callback function is called, it will become the status before calling this function, i.e., "this socket is opened".

If you call the SFXUDPSocket::Cancel function before the callback function is called, receiving data will be canceled and the status will be returned to the status before calling this function, i.e., "this socket is opened".

*1. If the SFXUDPSocket::Receive function returns AEE_NET_WOULDBLOCK, it will be necessary to register a callback function with this function where data will be received with the SFXUDPSocket::Receive function.

*2. If this function returns the value other than SFERR_NO_ERROR, the specified callback function will not be called.

	Note
	This function internally calls the SFBAStream::Readable function.

	Prerequisite
	This socket needs to be bound with the SFXUDPSocket::Bind function and not to be scheduled to receive data before this function is called.

Reference

SFXUDPSocket::Receive | SFBAStream::Readable | SFXStorage::CallbackSPP | BREW API ISOCKET_Readable

Return value

Description

This function schedules to send data onto this UDP socket without output stream.

Concretely, this function registers the callback function that will send data with the SFXUDPSocket::Send function. The registered callback function will be called by BREW AEE when it is possible to send data.

The status of this socket is "under scheduling to send data" until the callback function is called. And after the callback function is called, it will become the status before calling this function, i.e., "this socket is opened".

If you call the SFXUDPSocket::Cancel function before the callback function is called, sending data will be canceled and the status will be returned to the status before calling this function, i.e., "this socket is opened".

*1. If the SFXUDPSocket::Send function returns AEE_NET_WOULDBLOCK, it will be necessary to register a callback function with this function where data will be sent with the SFXUDPSocket::Send function.

*2. If this function returns the value other than SFERR_NO_ERROR, the specified callback function will not be called.

	Note
	This function internally calls the SFBSocket::Writeable function.

	Prerequisite
	This socket needs to be opened with the SFXUDPSocket::Open function and not to be scheduled to send data before this function is called.

Reference

SFXUDPSocket::Send | SFBSocket::Writeable | SFXStorage::CallbackSPP | BREW API ISOCKET_Writeable

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]

Reference

SFXStorage::CallbackSPP

Argument

Return value

Description

This function sends data onto this UDP socket without using any stream.

* If this function returns AEE_NET_WOULDBLOCK, it will be necessary to register a callback function with the SFXUDPSocket::ScheduleSend function where data will be sent with this function.

	Note
	This function internally calls the SFBSocket::SendTo function.

	Prerequisite
	This socket needs to be opened with the SFXUDPSocket::Open function before this function is called.

Reference

SFXUDPSocket::ScheduleSend | SFXUDPSocket::Open | SFXSocketAddress | SFBSocket::SendTo | BREW API ISOCKET_SendTo

Return value

SFERR_UNSUPPORTED

Description

[This function cannot be used now.]