SFXSSLSocket

Class for the SSL socket communication.

#include <SFXSSLSocket.h.hpp>

class SFXSSLSocket : public SFXStorage;

typedef SFXSSLSocket&          SFXSSLSocketRef;
typedef SFXSSLSocket*          SFXSSLSocketPtr;
typedef SFXSSLSocket*&         SFXSSLSocketPtrRef;
typedef SFXSSLSocket**         SFXSSLSocketHandle;
typedef const SFXSSLSocket     ConstSFXSSLSocket;
typedef const SFXSSLSocket&    ConstSFXSSLSocketRef;
typedef const SFXSSLSocket*    ConstSFXSSLSocketPtr;
typedef const SFXSSLSocket*&   ConstSFXSSLSocketPtrRef;
typedef const SFXSSLSocket**   ConstSFXSSLSocketHandle;

Inheritance diagram

Collaboration diagram

Description

SFXSSLSocket class encapsulates BREW API ISocket/ISSL interface and provides high level SSL socket communication functions.

How to use the SSL socket

Create the SSL socket(instance of SFXSSLSocket class).
Open the SSL socket using the SFXSSLSocket::Open function.
Set the trust mode(default: SSL_TRUST_MODE_FAIL) using the SFXSSLSocket::SetTrustMode function.
Connect to the TCP server using the SFXSSLSocket::Connect function. Register the address and port number(instance of SFXSocketAddress class) to be connected to and the callback function that will receive the notification of the connection establishment. Domain name is resolved automatically in the SFXSSLSocket class.
The callback function using the SFXSSLSocket::Connect function will be called after notified of the connection establishment.
Register the callback function that will receive the notification of negotiation completion(initialization for SSL communication) using the SFXSSLSocket::Negotiate function.
The callback function registered using the SFXSSLSocket::Negotiate function will be called after notified of the negotiation completion.
How to send data: Get the output stream (instance of SFXBinaryStreamWriter or SFXAnsiStringStreamWriter or SFXWideStringStreamWriter class) using the SFXSSLSocket::GetStreamWriter function. Write data through the output stream. And then send data actually using the SFXStreamWriter::Flush function. In the SFXStreamWriter::Flush function, register the callback function that will receive the notification of sending data actually. The processing after sending data should be described in this callback function.
How to receive data: Get the the input stream(instance of SFXBinaryStreamReader or SFXAnsiStringStreamReader or SFXWideStringStreamReader class) using the SFXSSLSocket::GetStreamReader. Receive data actually using the SFXStreamReader::Fetch function. In the SFXStreamReader::Fetch function, register the callback function that will receive the notification of receiving data actually. And then read data through the input stream in this callback function.
Repeat the above step 8. or 9. until no other data needs to be sent or received.
Finally, close the SSL socket using the SFXSSLSocket::Close function.

Example 492. Sample code for the SSL socket communication

// define _socket, instance of SFXSSLSocket class, as member variable
class MyClass {
private:
    SFXSSLSocket_socket;
    SFXAnsiStringStreamWriter _writer; // stream for sending data
    SFXAnsiStringStreamReader _reader; // stream for receiving data

public:
    Void Start(Void);

    // callback function
    CALLBACK_DECLARE_SFXSSLSOCKET(OnConnect)
    CALLBACK_DECLARE_SFXSSLSOCKET(OnNegotiate)
    CALLBACK_DECLARE_SFXANSISTRINGSTREAMWRITER(OnFlush)
    CALLBACK_DECLARE_SFXANSISTRINGSTREAMREADER(OnFetch)
};

Void MyClass::Start(Void)
{
    SFCError error;
    SFXSocketAddress host("www.example.com:995");

    // open TCP socket
    if ((error = _socket.Open()) == SFERR_NO_ERROR) {
 
        // host name is automatically resolved
        // connect to TCP server
        // connection establishment will be notified to OnConnect function 
        error = _socket.Connect(host, CALLBACK_FUNCTION(OnConnect));
    }
    if (error != SFERR_NO_ERROR) { 
        // if error occurs
        _socket.Close();
    }
    return;
}

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXSSLSOCKET(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) { 
        // no error
        // negotiate
        // negotiation completion will be notified to OnNegotiate function 
        error = _socket.Negotiate(CALLBACK_FUNCTION(OnNegotiate));
    }
    if (error != SFERR_NO_ERROR) { 
        // if error occurs
        _socket.Close();
    }
    return;
}

// callback function notified of negotiation completion
CALLBACK_IMPLEMENT_SFXSSLSOCKET(MyClass, OnNegotiate, error)
{
    static AChar sendingMessage[] = "GET / HTTP/1.0\r\n\r\n";

    if (error == SFERR_NO_ERROR) {

        // get the stream for data sending (buffer size: 1024 )
        if ((error = _socket.GetStreamWriter(1024, &_writer))
            == SFERR_NO_ERROR) {

            // write the data
            if ((error = _writer.Write(sendingMessage,
                   lengthof(sendingMessage))) == SFERR_NO_ERROR) {

                // send data actually
                // completion of sending data actually will be notified to OnFlush function 
                error = _writer.Flush(CALLBACK_FUNCTION(OnFlush));
            }
            if (error != SFERR_NO_ERROR) { 
                // if error occurs
                 _writer.Release();
            }
        }
    }
    if (error != SFERR_NO_ERROR) { 
       // if error occurs
       _socket.Close();
    }
    return;
}

// callback function notified of completion of sending data actually
CALLBACK_IMPLEMENT_SFXANSISTRINGSTREAMWRITER(MyClass, OnFlush, error)
{
    // sending completed, release the stream for the data sending
    _writer.Release();

    if (error == SFERR_NO_ERROR) {

        // get input stream for receiving data (buffer size: 1024 )
        if ((error = _socket.GetStreamReader(1024, &_reader))
            == SFERR_NO_ERROR) {

            // receive data actually
            // completion of receiving data actually will be notified to onFetch function
            if ((error = _reader.Fetch(CALLBACK_FUNCTION(OnFetch)))
                != SFERR_NO_ERROR) {
                // if error occurs
               _reader.Release(); 
            }
        }
    }
    if (error != SFERR_NO_ERROR) { 
        // if error occurs
        _socket.Close();
    }
    return;
}

// callback function notified of completion of receiving data actually
CALLBACK_IMPLEMENT_SFXANSISTRINGSTREAMREADER(MyClass, OnFetch, error)
{
    SFXAnsiString receivedString;

    if (error == SFERR_NO_ERROR) {

        // read data through input stream
        _reader >> receivedString;

        // display response
        TRACE("%s", receivedString.GetCString());
    }
    // release input stream after receiving data
    _reader.Release();

    // close socket
    _socket.Close();
    return;
}

Reference

SFXTCPSocket | SFXUDPSocket | Socket Connection

Member

Constructor/Destructor
SFXSSLSocket( `Void` ) Constructor of SFXSSLSocket class.
~SFXSSLSocket( `Void` ) Destructor of SFXSSLSocket class.

Public Functions
`SFCError`	AsSFBAStream( `SFBAStreamSmpPtr` result ) Convert the instance of SFBSocket class internally managed into the instance of SFBAStream class.
`SFCError`	AsSFBSource( `SFBSourceSmpPtr` result ) Convert the instance of SFBSocket class internally managed into the instance of SFBSource class.
`SFCError`	Bind( `SFXSocketAddressConstRef` address ) Bind the local IP address and port number to the socket.
`Void`	Cancel( `Void` ) Cancel the SSL socket communication.
`Void`	Close( `Void` ) Close the SSL Socket.
`SFCError`	Connect( `SFXSocketAddressConstRef` address , `CallbackSPP` spp , `VoidPtr` reference ) Connect to the TCP server over SSL.
`SFCError`	GetLocalAddress( `SFXSocketAddressPtr` result ) Get the local IP address and port number.
`SFCError`	GetRemoteAddress( `SFXSocketAddressPtr` result ) Get the remote IP address and port number.
`SFBSSLSmpConstRef`	GetSFBSSL( `Void` ) Get the instance of SFBSSL class that is internally used.
`SFBSocketSmpConstRef`	GetSFBSocket( `Void` ) Get the socket that is internally used.
`SFCError`	GetStreamReader( `UInt32` size , `SFXStreamReaderPtr` result ) GetStreamReader( `SFXStreamReaderPtr` result ) Get the input stream for reading data from the SSL socket.
`SFCError`	GetStreamWriter( `UInt32` size , `SFXStreamWriterPtr` result ) GetStreamWriter( `SFXStreamWriterPtr` result ) Get the output stream for writing data to the SSL socket.
`UInt32`	GetTrustMode( `Void` ) Get the SSL trust mode.
`SFCError`	Negotiate( `CallbackSPP` spp , `VoidPtr` reference ) Perform the Negotiation for the SSL socket communication.
`SFCError`	Open( `Void` ) Open the SSL socket.
`SFCError`	Permit( `Void` ) Set to perform the communication that does not use SSL.
`SFCError`	Read( `VoidPtr` buffer , `UInt32Ptr` size ) Receive data.
`SFCError`	ScheduleBind( `CallbackSPP` spp , `VoidPtr` reference ) Schedule to bind.
`SFCError`	ScheduleRead( `CallbackSPP` spp , `VoidPtr` reference ) Schedule to receive data.
`SFCError`	ScheduleWrite( `CallbackSPP` spp , `VoidPtr` reference ) Schedule to send data.
`SFCError`	SetTrustMode( `UInt32` param ) Set the SSL trust mode.
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32Ptr` size ) Send data.

Types
CallbackSPP (inherits from SFXStorage) The prototype of the callback function for the SFXStorage class.

SFXSSLSocket::SFXSSLSocket

Constructor of SFXSSLSocket class.

[ public, explicit ]
SFXSSLSocket(Void);

Description

The instances of SFBNetMgr, SFBSocket, SFBSSL, and SFBSSLRootCerts classes are not created in the constructor.

SFXSSLSocket::~SFXSSLSocket

Destructor of SFXSSLSocket class.

[ public, virtual ]
virtual ~SFXSSLSocket(Void);

Description

The SFXSSLSocket::Close function is called in the destructor.

Reference

SFXSSLSocket::Close

SFXSSLSocket::AsSFBAStream

Convert the instance of SFBSocket class internally managed into the instance of SFBAStream class.

[ public, virtual, const ]
SFCError AsSFBAStream(
    SFBAStreamSmpPtr result   // pointer to the result SFBAStream class instance
);

Return value

Success : SFERR_NO_ERROR
Socket has been closed : SFERR_INVALID_STATE
Argument is null : SFERR_INVALID_PARAM

Reference

SFBSocket | SFBAStream

SFXSSLSocket::AsSFBSource

Convert the instance of SFBSocket class internally managed into the instance of SFBSource class.

[ public, virtual, const ]
SFCError AsSFBSource(
    SFBSourceSmpPtr result   // pointer to the result SFBSource class instance
);

Return value

Success : SFERR_NO_ERROR
If socket has been closed : SFERR_INVALID_STATE
If argument is null : SFERR_INVALID_PARAM
If failed to convert : SFERR_FAILED

Description

The SFXSSLSocket::AsSFBSource function creates and releases the instance of SFBSourceUtil class used internally.

Reference

SFBSocket | SFBSource

SFXSSLSocket::Bind

Bind the local IP address and port number to the socket.

[ public ]
SFCError Bind(
    SFXSocketAddressConstRef address   // IP address and port number
);

Return value

Success : SFERR_NO_ERROR
If socket has been closed : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY
If operation is blocked : AEE_NET_WOULDBLOCK
If other network error occurs: To get the error value, call the SFBSocket::GetLastError function.

Description

When the return value of SFXSSLSocket::Bind function is AEE_NET_WOULDBLOCK, register the callback function using the SFXSSLSocket::ScheduleBind function, and then schedule the SFXSSLSocket::Bind function in the callback function again.

Reference

SFXSSLSocket::ScheduleBind

SFXSSLSocket::Cancel

Cancel the SSL socket communication.

[ public, virtual ]
Void Cancel(Void);

SFXSSLSocket::Close

Close the SSL Socket.

[ public ]
Void Close(Void);

Description

Cancel the SSL socket communication, and then the ISocket and INetMgr interfaces used internally are released.

When the BREW application is suspended, call the SFXSSLSocket::Close function to release the resources.

SFXSSLSocket::Connect

Connect to the TCP server over SSL.

[ public ]
SFCError Connect(
    SFXSocketAddressConstRef address   // domain (or IP address) and port number
    CallbackSPP spp                    // callback function
    VoidPtr reference                  // data passed to callback function
);

Argument

address: Specify domain (or IP address) and port number. The SFXSSLSocket class will automatically resolve the domain when needed.
spp: Specify the callback function notified of connection establishment.
reference: Specify the data passed to the callback function.

Return value

Success : SFERR_NO_ERROR
If socket is not opened or it has already been connected (including under processing) : SFERR_INVALID_STATE
If domain name is not found : SFERR_INVALID_STATE
If failed to create the instance of SFBNetMgr class : SFERR_FAILED
If insufficient memory : SFERR_NO_MEMORY
If other network error occurs: To get the error value, call the SFBSocket::GetLastError function.

Description

The connection establishment is notified to the callback function registered using the SFXSSLSocket::Connect function.

	Errors during the connection
	The return value does not include the errors while connecting to the TCP server, which are notified to the callback function.

SFXSSLSocket::GetLocalAddress

Get the local IP address and port number.

[ public, const ]
SFCError GetLocalAddress(
    SFXSocketAddressPtr result   // pointer to the local IP address and port number
);

Return value

Success : SFERR_NO_ERROR
If socket is not opened or Bind has not been done : SFERR_INVALID_STATE
If argument is null : SFERR_INVALID_PARAM
If other network error occurs: To get the error value, call the SFBSocket::GetLastError function.

Description

	Change of Local IP address
	The local IP address might be changed between before and after the SSL socket connection.

Reference

SFXInetAddress::LocalInetAddress

SFXSSLSocket::GetRemoteAddress

Get the remote IP address and port number.

[ public, const ]
SFCError GetRemoteAddress(
    SFXSocketAddressPtr result   // pointer to the remote IP address and port number
);

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If argument is null : SFERR_INVALID_PARAM
If other network error occurs: To get the error value, call the SFBSocket::GetLastError function.

Description

	Change of Remote IP address
	The remote IP address might be changed between before and after the SSL socket connection.

SFXSSLSocket::GetSFBSSL

Get the instance of SFBSSL class that is internally used.

[ public, const ]
SFBSSLSmpConstRef GetSFBSSL(Void);

Reference

SFBSSL

SFXSSLSocket::GetSFBSocket

Get the socket that is internally used.

[ public, const ]
SFBSocketSmpConstRef GetSFBSocket(Void);

Description

Get the socket (instance of SFBSocket class) that is used internally.

Reference

SFBSocket

SFXSSLSocket::GetStreamReader

Get the input stream for reading data from the SSL socket.

[ public, virtual ]
SFCError GetStreamReader(
    UInt32 size                 // buffer size
    SFXStreamReaderPtr result   // pointer to the input stream
);

[ public, virtual ]
SFCError GetStreamReader(
    SFXStreamReaderPtr result   // pointer to the input stream
);

Return value

Success : SFERR_NO_ERROR
If argument is null : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The buffer size of the input stream can be specified. Use the SFXBinaryStreamReader, SFXAnsiStringStreamReader, or SFXWideStringStreamReader class for the input stream properly according to the type of data to read.

Reference

SFXSSLSocket::GetStreamWriter | SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader

SFXSSLSocket::GetStreamWriter

Get the output stream for writing data to the SSL socket.

[ public, virtual ]
SFCError GetStreamWriter(
    UInt32 size                 // buffer size
    SFXStreamWriterPtr result   // pointer to the output stream
);

[ public, virtual ]
SFCError GetStreamWriter(
    SFXStreamWriterPtr result   // pointer to the output stream
);

Return value

Success : SFERR_NO_ERROR
If argument is null : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The buffer size of the output stream can be specified. Use the SFXBinaryStreamWriter, SFXAnsiStringStreamWriter, or SFXWideStringStreamWriter class for the output stream properly according to the written data type

Reference

SFXSSLSocket::GetStreamReader | SFXBinaryStreamWriter | SFXAnsiStringStreamWriter | SFXWideStringStreamWriter

SFXSSLSocket::GetTrustMode

Get the SSL trust mode.

[ public, const ]
UInt32 GetTrustMode(Void);

Description

The SSL trust mode can be one of the following values.

SSL_TRUST_MODE_FAIL
SSL_TRUST_MODE_CHECK
SSL_TRUST_MODE_IGNORE
SSL_TRUST_MODE_ALWAYS

	Note
	Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXSSLSocket::SetTrustMode

SFXSSLSocket::Negotiate

Perform the Negotiation for the SSL socket communication.

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

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If failed to create the instance of SFBSSLRootCerts class : SFERR_FAILED
If insufficient memory : SFERR_NO_MEMORY

Description

Perform the Negotiation for the SSL socket communication after the connection is established by the SFXSSLSocket::Connect function.

Reference

SFXSSLSocket::Connect

SFXSSLSocket::Open

Open the SSL socket.

[ public ]
SFCError Open(Void);

Return value

Success : SFERR_NO_ERROR
If socket has already been opened : SFERR_INVALID_STATE
If failed to create the instance of SFBNetMgr or SFBSSL class : SFERR_FAILED
Otherwise : AEE_NET_ERROR

Description

Create the instances of SFBNetMgr and SFBSSL classes and open the SSL socket (instance of SFBSocket class).

Reference

SFBNetMgr | SFBSSL | SFBSocket

SFXSSLSocket::Permit

Set to perform the communication that does not use SSL.

[ public ]
SFCError Permit(Void);

Return value

Success : SFERR_NO_ERROR
If connection has not been established, or after Negotiation is established.

Description

After the connection is established, communication without using SSL is available if calling the SFXSSLSocket::Permit function before Negotiation or after Negotiation failed.

Reference

SFXSSLSocket::Negotiate

SFXSSLSocket::Read

Receive data.

[ public, virtual ]
SFCError Read(
    VoidPtr buffer   // buffer that stores the received data
    UInt32Ptr size   // buffer size
);

Argument

buffer: Specify the buffer to store the received data.
size: Specify the buffer size when calling the SFXSSLSocket::Read function. After the SFXSSLSocket::Read function is executed, the size of received data is stored.

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If size is null : SFERR_INVALID_PARAM
If necessary to retry : AEE_NET_WOULDBLOCK
If impossible to receive : AEE_NET_ERROR

Description

To receive data without using the input stream, use the SFXSSLSocket::Read function.

When the return value of SFXSSLSocket::Read function is AEE_NET_WOULDBLOCK, register the callback function using the SFXSSLSocket::ScheduleRead function, and then schedule the SFXSSLSocket::Read function in the callback function again.

Reference

SFXSSLSocket::ScheduleRead

SFXSSLSocket::ScheduleBind

Schedule to bind.

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

Return value

Success : SFERR_NO_ERROR
If socket has been closed, or the callback has already been registered : SFERR_INVALID_STATE

Description

The SFXSSLSocket::ScheduleBind function is used to register the callback function in which Bind is done using the SFXSSLSocket::Bind function.

	Note
	When the return value of `SFXSSLSocket::Bind` function is AEE_NET_WOULDBLOCK, register the callback function using the SFXSSLSocket::ScheduleBind function, and then schedule the `SFXSSLSocket::Bind` function in the callback function again.

Reference

SFXSSLSocket::Bind

SFXSSLSocket::ScheduleRead

Schedule to receive data.

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

Return value

Success : SFERR_NO_ERROR
If connection has not been established, or the callback function has already been registered : SFERR_INVALID_STATE

Description

The SFXSSLSocket::ScheduleRead function is used to register the callback function in which the SFXSSLSocket::Read function is used to receive data.

	Note
	When the return value of `SFXSSLSocket::Read` function is AEE_NET_WOULDBLOCK, register the callback function using the SFXSSLSocket::ScheduleRead function, and then schedule the `SFXSSLSocket::Read` function in the callback function again.

Reference

SFXSSLSocket::Read

SFXSSLSocket::ScheduleWrite

Schedule to send data.

[ public, virtual ]
SFCError ScheduleWrite(
    CallbackSPP spp     // callback function
    VoidPtr reference   // pointer to callback function
);

Return value

Success : SFERR_NO_ERROR
If connection has not been established, or the callback function has already been registered : SFERR_INVALID_STATE

Description

The SFXSSLSocket::ScheduleWrite function is used to register the callback function in which the SFXSSLSocket::Write function is used to send data.

	Note
	When the return value of `SFXSSLSocket::Write` function is AEE_NET_WOULDBLOCK, register the callback function using the SFXSSLSocket::ScheduleWrite function, and then schedule the `SFXSSLSocket::Write` function in the callback function again.

Reference

SFXSSLSocket::Write

SFXSSLSocket::SetTrustMode

Set the SSL trust mode.

[ public ]
SFCError SetTrustMode(
    UInt32 param   // sSL verificatio mode
);

Return value

Success : SFERR_NO_ERROR
If socket has been closed : SFERR_INVALID_STATE

Description

The value set by the SFXSSLSocket::SetTrustMode function is valid until the SFXSSLSocket::Close function is called.

The SSL_RESULT_SERV_VERS error might occur on the real device when calling the SFXSSLSocket::Connect function immediately after this value is changed.

To avoid this error, call the SFXSSLSocket::Close function once, set the SSL trust mode, and then call the SFXSSLSocket::Connect function.

One of the following values are available for the SSL trust mode:

SSL_TRUST_MODE_FAIL: Default, fail on trust errors.
SSL_TRUST_MODE_CHECK: Suspend on trust errors so they can be checked and ignored.
SSL_TRUST_MODE_IGNORE: Ignore all trust errors.
SSL_TRUST_MODE_ALWAYS: Always suspend so trust can always be checked.

	Note
	Detailed information: ISSL_NegotiateV in the BREW API Reference

SFXSSLSocket::Write

Send data.

[ public, virtual ]
SFCError Write(
    VoidConstPtr buffer   // data to write
    UInt32Ptr size        // size of data to write
);

Argument

buffer: Data to write.
size: Specify the buffer size when calling the SFXSSLSocket::Write function. After the SFXSSLSocket::Write function is executed, the size of actually written data is stored.

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If size is null : SFERR_INVALID_PARAM
If necessary to retry : AEE_NET_WOULDBLOCK
If impossible to receive : AEE_NET_ERROR

Description

To write data without using the output stream, use the SFXSSLSocket::Write function.

When the return value of SFXSSLSocket::Write function is AEE_NET_WOULDBLOCK, register the callback function using the SFXSSLSocket::ScheduleWrite function, and then schedule the SFXSSLSocket::Write function in the callback function again.

Reference

SFXSSLSocket::ScheduleWrite