SFXHTTPConnection

Class for the HTTP communication.

#include <SFXHTTPConnection.h.hpp>

class SFXHTTPConnection;

SFMTYPEDEFCLASS(SFXHTTPConnection)

Collaboration diagram

Description

The SFXHTTPConnection class provides the functions necessary for the HTTP and HTTPS communication similar to those of com.nttdocomo.io.HttpConnection class implemented in the NTT DoCoMo development environment for Mobile Java applications( DoJa).

	Note
	The `SFXHTTPConnection` class is implemented using the IWeb, IWebResp, and IX509Chain interfaces of BREW APIs.

State transition of the HTTP connection

The HTTP connection(SFXHTTPConnection instance) transits among three kinds of states below(strictly, four kinds of them).

Table 192. State of the HTTP connection

State of the HTTP connection Description

State of the HTTP connection	Description
`STATE_CLOSE`	This state represents the state that the HTTP connection has not been initialized. After the `SFXHTTPConnection` instance is created (i.e., the `SFXHTTPConnection::SFXHTTPConnection` constructor is executed) or the `SFXHTTPConnection::Close` function is executed, the HTTP connection will transit into the STATE_CLOSE state.
`STATE_OPEN(STATE_OPEN_UNESTABLISHED/STATE_OPEN_ESTABLISHED)`	This state represents the states before connecting to the Web server and after connection to the Web server is established. In both of the above states, the HTTP connection has been initialized. For convenience, in this reference, these two states are called STATE_OPEN_UNESTABLISHED and STATE_OPEN_ESTABLISHED respectively. (STATE_OPEN represents the state that these two states are put together). If the `SFXHTTPConnection::Open` function is called in the STATE_CLOSE state, the HTTP connection will transit into the STATE_OPEN_UNESTABLISHED state. And, if the `SFXHTTPConnection::Clear` function is called in the STATE_OPEN_ESTABLISHED state, the HTTP connection will transit into the STATE_OPEN_UNESTABLISHED state.
`STATE_CONNECT`	This state represents the state during connecting to the Web server. If the `SFXHTTPConnection::Connect` function is called in the STATE_OPEN state, the HTTP connection will transit into the STATE_CONNECT state. However, when the result of this connection is passed to the callback function specified in this function, it will return into the STATE_OPEN state again(in case of success, STATE_OPEN_ESTABLISHED; otherwise, STATE_OPEN_UNESTABLISHED).

STATE_CLOSE

This state represents the state that the HTTP connection has not been initialized.

After the SFXHTTPConnection instance is created (i.e., the SFXHTTPConnection::SFXHTTPConnection constructor is executed) or the SFXHTTPConnection::Close function is executed, the HTTP connection will transit into the STATE_CLOSE state.

STATE_OPEN(STATE_OPEN_UNESTABLISHED/STATE_OPEN_ESTABLISHED)

This state represents the states before connecting to the Web server and after connection to the Web server is established. In both of the above states, the HTTP connection has been initialized.

For convenience, in this reference, these two states are called STATE_OPEN_UNESTABLISHED and STATE_OPEN_ESTABLISHED respectively. (STATE_OPEN represents the state that these two states are put together).

If the SFXHTTPConnection::Open function is called in the STATE_CLOSE state, the HTTP connection will transit into the STATE_OPEN_UNESTABLISHED state. And, if the SFXHTTPConnection::Clear function is called in the STATE_OPEN_ESTABLISHED state, the HTTP connection will transit into the STATE_OPEN_UNESTABLISHED state.

STATE_CONNECT

This state represents the state during connecting to the Web server.

If the SFXHTTPConnection::Connect function is called in the STATE_OPEN state, the HTTP connection will transit into the STATE_CONNECT state. However, when the result of this connection is passed to the callback function specified in this function, it will return into the STATE_OPEN state again(in case of success, STATE_OPEN_ESTABLISHED; otherwise, STATE_OPEN_UNESTABLISHED).

Callback function

	Callback function
To connect to the Web server, call the `SFXHTTPConnection::Connect` function. The error code as the result of this connection will be passed to the first argument of the callback function specified in this function. In case the error code is SFERR_NO_ERROR, it succeeds to obtain the HTTP response. In this case, it will transit into the STATE_OPEN_ESTABLISHED state. In case of SFERR_FAILED, it fails to obtain the HTTP response. In this case, it will transit into the STATE_OPEN_ESTABLISHED state.

To connect to the Web server, call the SFXHTTPConnection::Connect function. The error code as the result of this connection will be passed to the first argument of the callback function specified in this function.

In case the error code is SFERR_NO_ERROR, it succeeds to obtain the HTTP response. In this case, it will transit into the STATE_OPEN_ESTABLISHED state. In case of SFERR_FAILED, it fails to obtain the HTTP response. In this case, it will transit into the STATE_OPEN_ESTABLISHED state.

How to implement the HTTP client

The HTTP client can be implemented by taking the following procedures with the SFXHTTPConnection class.

Create the SFXHTTPConnection instance, that is, the HTTP connection.
Open the HTTP connection using the SFXHTTPConnection::Open function.
Set the HTTP request method(default: GET method) using the SFXHTTPConnection::SetMethod function. And set data to the HTTP request body through the output stream obtained by the SFXHTTPConnection::GetStreamWriter function. Set the HTTP request header using the SFXHTTPConnection::SetRequestHeader function, if necessary. (* The HTTP request body can be set using the SFXHTTPConnection::SetRequestContent function.)
In case of the HTTPS connection, set the trust mode(default: SSL_TRUST_MODE_FAIL) using the SFXHTTPConnection::SetTrustMode function.
Connect to the Web server using the SFXHTTPConnection::Connect function, in which set the URL to be connected to and register the callback function notified of the result of HTTP connection request.
The callback function above will be called after notified of the result of connecting to the Web server. (* The execution result(error code) of connecting to the Web server will be passed to the callback function through the 1st argument. If the error code is "SFERR_NO_ERROR", connecting to the Web server is succeeded and the HTTP response is obtained.)
After checking the value of HTTP status code using the SFXHTTPConnection::GetResultCode function, read the HTTP response body through the input stream obtained by the SFXHTTPConnection::GetStreamReader function. The HTTP response header can be gotten using the SFXHTTPConnection::GetResponseHeader function. (* The HTTP response body can be gotten using the SFXHTTPConnection::GetResponseContent function.)
Repeat the above steps from 2. to 7. until no other data needs to be written or read.
Finally, close HTTP connection using the SFXHTTPConnection::Close function.

Example 820. Sample code for the HTTP communication

// The _http variable is defined as class member variable since used in the callback function
class MyClass {
private:
    SFXHTTPConnection _http;
    SFXAnsiStringStreamReader _reader;
    SFXAnsiString _string;
public:
    Void Start(Void);
    XALLBACK_DECLARE_SFXHTTPCONNECTION(OnConnect)
    XALLBACK_DECLARE_SFXANSISTRINGSTREAMREADER(OnFetch)
};

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

    // initialize HTTP connection
    if ((error = _http.Open()) == SFERR_NO_ERROR) {
    
        // set HTTP request method to "GET"
        // if this setting is obmitted, "GET" is set by default
        _http.SetMethod("GET");

        // start to connect
#if 1
        // HTTP connection
        // the connection result will be notified to the OnConnect function
        if ((error = _http.Connect("http://www.example.com/", XALLBACK_INTERNAL(OnConnect))) == SFERR_NO_ERROR) {
#else
        // HTTPS connection
        // set trust mode if needed
        // the connection result will be notified to the OnConnect function
        _http.SetTrustMode(SSL_TRUST_MODE_FAIL);
        if ((error = _http.Connect("https://www.example.com/", XALLBACK_INTERNAL(OnConnect))) == SFERR_NO_ERROR) {
#endif
            ...
        }
    }

    if (error != SFERR_NO_ERROR) {

        // if an error occurs
        _http.Close();
    }
    return;
}

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    SFXPropertyConstPtr header;
    SInt16 i;

    if (error == SFERR_NO_ERROR) {
        
        // display parameters

        // get the HTTP status code
        TRACE("result code = %d", _http.GetResultCode());
        // get Content-Length field of the HTTP response header
        TRACE("content length = %d", _http.GetLength()); 
        // get Content-Type field of the HTTP response header
        TRACE("content type = %s", _http.GetType().GetCString());
        // get Content-Encoding field of the HTTP response header
        TRACE("content encoding = %s", _http.GetEncoding().GetCString());
        // get Date field of the HTTP response header
        TRACE("date = %s", _http.GetDate().Format("YYYY/MM/DD hh:mm:ss").GetCString());
        // get Expires field of the HTTP response header
        TRACE("expires = %s", _http.GetExpires().Format("YYYY/MM/DD hh:mm:ss").GetCString());
        // get Last-Modified field of the HTTP response header
        TRACE("last modified = %s", _http.GetLastModified().Format("YYYY/MM/DD hh:mm:ss").GetCString());

        
        // get the HTTP response header
        header = &_http.GetResponseHeader();
        
        // display HTTP response header
        for (i = 0; i < header->GetSize(); ++i) {
            TRACE("%s: %s", header->GetKey(i).GetCString(), header->GetValue(i).GetCString());
        }

        if (_http.GetResultCode() == 200) {

            // get input stream for reading data from HTTP response body
            if ((error = _http.GetStreamReader(1024, &_reader)) == SFERR_NO_ERROR) {

                // the fetch result will be notified to the OnFetch function
                if ((error = _reader.Fetch(XALLBACK_INTERNAL(OnFetch))) == SFERR_NO_ERROR) {

                    ...
                }
            }
        }
        else {

            error = SFERR_INVALID_STATE;
        }
    }

    if (error != SFERR_NO_ERROR) {

        // if an error occurs
       _http.Close();
    }
    return;
}

// callback function notified of the fetch result
XALLBACK_IMPLEMENT_SFXANSISTRINGSTREAMREADER(MyClass, OnFetch, error)
{
    SFXAnsiString string;

    if (error == SFERR_NO_ERROR) {

        // read data from input stream buffer into the string variable
        if ((error = _reader.ReadSFXAnsiString(&string)) == SFERR_NO_ERROR) {

            // add the string variable to the _string variable
            if ((error = _string.Add(string)) == SFERR_NO_ERROR) {

                // check whether or not data is still remaining
                if (_reader.Ends()) {

                    // since all data have been read, display them on BREW Output Window
                    TRACE("--------");
                    TRACE("%s", _string.GetCString());
                    TRACE("--------");

                    // release resources explicitly
                    _reader.Release();
                    _http.Close();
                }
                else {

                    // read data from HTTP response body into input stream buffer
                    // the fetch result will be notified to the OnFetch function
                    error = _reader.Fetch(XALLBACK_INTERNAL(OnFetch));
                }
            }
        }
    }

    if (error != SFERR_NO_ERROR) {

        // if an error occurs
        _reader.Release();
        _http.Close();
    }
    return;
}

Limitation on the IWeb Interface in BREW 2.0 / 2.1

In case of BREW 2.0: Data that is greater than or equals 1536 bytes cannot be sent.

In case of BREW 2.1: Data that is greater than or equals 65536 bytes cannot be sent.

Reference

BREW API IWeb | BREW API IWebResp | BREW API IX509Chain | SFXTCPSocket | HTTP connection

Member

Constructor/Destructor
SFXHTTPConnection( `Void` ) Constructor of the SFXHTTPConnection class.
~SFXHTTPConnection( `Void` ) Destructor of the SFXHTTPConnection class.

Public Functions
`Void`	Cancel( `Void` ) Cancel to connect to the Web server.
`SFCError`	Clear( `Void` ) Initialize the internal variables of this HTTP connection.
`Void`	Close( `Void` ) Close this HTTP connection.
`SFCError`	Connect( `SFXAnsiStringConstRef` url , `CallbackSPP` spp , `VoidPtr` reference ) Connect to the Web server.
`SFXAnsiStringConstRef`	GetBaseUrl( `Void` ) Get the base URL of HTTP basic authentication.
`SFXDate`	GetDate( `Void` ) Get the value of the Date field of the HTTP response header.
`SFXAnsiStringConstRef`	GetEncoding( `Void` ) get the value of the Content-Encoding field of the HTTP response header.
`SFXDate`	GetExpires( `Void` ) Get the value of the Expires field of the HTTP response header.
`SFXDate`	GetLastModified( `Void` ) Get the value of the Last-Modified field of the HTTP response header.
`SInt32`	GetLength( `Void` ) Get the value of the Content-Length field of the HTTP response header.
`SFXAnsiStringConstRef`	GetMethod( `Void` ) Get the HTTP request method.
`SFXAnsiStringConstRef`	GetPassword( `Void` ) Get the password of HTTP basic authentication.
`SFXSocketAddressConstRef`	GetProxyServer( `Void` ) Get the proxy server.
`SFBSourceSmpConstRef`	GetRequestContent( `Void` ) Get the SFBSource instance that manages the HTTP request body.
`UInt32`	GetRequestFlag( `Void` ) Get the HTTP request flag.
`SFXAnsiStringConstRef`	GetRequestHeader( `SFXAnsiStringConstRef` key ) Get the HTTP request header.
`SFXPropertyConstRef`	GetRequestHeader( `Void` ) Get the HTTP request header.
`SFBSourceSmpConstRef`	GetResponseContent( `Void` ) Get the SFBSource instance that manages the HTTP response body.
`UInt32`	GetResponseFlag( `Void` ) Get the HTTP response flag.
`SFXAnsiStringConstRef`	GetResponseHeader( `SFXAnsiStringConstRef` key ) Get the HTTP response header.
`SFXPropertyConstRef`	GetResponseHeader( `Void` ) Get the HTTP response header.
`SInt32`	GetResultCode( `Void` ) Get the HTTP status code.
`SFBWebSmpConstRef`	GetSFBWeb( `Void` ) Get the SFBWeb instance managed internally by this HTTP connection.
`SFBWebRespSmpConstRef`	GetSFBWebResp( `Void` ) Get the SFBWebResp instance managed internally by this HTTP connection.
`StateEnum`	GetState( `Void` ) Get the state of the HTTP/HTTPS connection.
`SFCError`	GetStreamReader( `UInt32` size , `SFXStreamReaderPtr` result ) Get the input stream for reading data from the HTTP response body.
`SFCError`	GetStreamReader( `SFXStreamReaderPtr` result ) Get the input stream for reading data from the HTTP response body.
`SFCError`	GetStreamWriter( `UInt32` size , `SFXStreamWriterPtr` result ) Get the output stream for writing data onto the HTTP request body.
`SFCError`	GetStreamWriter( `SFXStreamWriterPtr` result ) Get the output stream for writing data onto the HTTP request body.
`UInt32`	GetTimeoutMillisecond( `Void` ) Get the connection timeout period. [in milliseconds]
`UInt32`	GetTrustMode( `Void` ) Get the SSL trust mode.
`SFXAnsiStringConstRef`	GetType( `Void` ) Get the value of the Content-Type field of the HTTP response header.
`SFXAnsiStringConstRef`	GetUser( `Void` ) Get the user name of HTTP basic authentication.
`SFXAnsiStringConstRef`	GetUserAgent( `Void` ) Get the user agent of the HTTP request header.
`SFCError`	Open( `AEECLSID` id = AEECLSID_WEB ) Open this HTTP connection.
`SFCError`	SetAuthorizeData( `SFXAnsiStringConstRef` user , `SFXAnsiStringConstRef` passwd , `SFXAnsiStringConstRef` url ) Set the information of HTTP basic authentication.
`SFCError`	SetMethod( `SFXAnsiStringConstRef` param ) Set the HTTP request method.
`SFCError`	SetProxyServer( `SFXSocketAddressConstRef` param ) Set the proxy server.
`SFCError`	SetRequestContent( `SFXFileConstRef` file ) Set the HTTP request body of this HTTP connection to the specified storage or source.
`SFCError`	SetRequestContent( `SFXMemoryConstRef` memory ) Set the HTTP request body of this HTTP connection to the specified storage or source.
`SFCError`	SetRequestContent( `SFXStorageConstRef` storage , `SInt32` length ) Set the HTTP request body of this HTTP connection to the specified storage or source.
`SFCError`	SetRequestContent( `SFBSourceSmpConstRef` source , `SInt32` length ) Set the HTTP request body of this HTTP connection to the specified storage or source.
`SFCError`	SetRequestFlag( `UInt32` param ) Set the HTTP request flag.
`SFCError`	SetRequestHeader( `SFXAnsiStringConstRef` key , `SFXAnsiStringConstRef` value ) Set the HTTP request header.
`Void`	SetTimeoutCallback( `SFXCallback::CallbackSPP` spp , `VoidPtr` reference ) Set the connection timeout callback.
`Void`	SetTimeoutMillisecond( `UInt32` msec ) Set the connection timeout period to the specified value. [in milliseconds]
`SFCError`	SetTrustMode( `UInt32` param ) Set the SSL trust mode.
`SFCError`	SetUserAgent( `SFXAnsiStringConstRef` param ) Set the user agent.
`SFCError`	LoadCertificate( `SInt32` kind , `SFXPathConstRef` path ) (inherits from LoadCertificate) Load a ASN.1/DER form certificate file or buffer.
`SFCError`	LoadCertificate( `SInt32` kind , `SFXBufferConstRef` buffer ) (inherits from LoadCertificate) Load a ASN.1/DER form certificate file or buffer.

Types
CallbackSPP Type that represents the callback function.
StateEnum Enumeration which represents the state of the HTTP/HTTPS connection.

SFXHTTPConnection::SFXHTTPConnection

Constructor of the SFXHTTPConnection class.

[ public, explicit ]
SFXHTTPConnection(Void);

Description

This constructor performs the initializations as follows:

Intialize the state of this HTTP connection as "closed"(STATE_CLOSE).
Set the default connection timeout period to 0. (In this case, connection timeout processing will not be performed.)
Register the SFXHTTPConnection::OnTimeoutDefault fucntion as the default connection timeout callback.

Note

	Note
After this constructor is executed, the state of this HTTP connection is STATE_CLOSE. To connect the Web server, it is necessary to open this HTTP connection with the `SFXHTTPConnection::Open` function.

After this constructor is executed, the state of this HTTP connection is STATE_CLOSE.

To connect the Web server, it is necessary to open this HTTP connection with the SFXHTTPConnection::Open function.

Reference

SFXHTTPConnection::Open | SFXHTTPConnection::SetTimeoutMillisecond | SFXHTTPConnection::SetTimeoutCallback

SFXHTTPConnection::~SFXHTTPConnection

Destructor of the SFXHTTPConnection class.

[ public ]
~SFXHTTPConnection(Void);

Description

This destructor calls the SFXHTTPConnection::Close function internally.

Concretely, the contents of the HTTP request and the HTTP response will be initialized, the SFBWeb / SFBWebResp instance that this HTTP connection contains internally will be released, the state of this HTTP connection will become "closed", and the callback registered into this HTTP connection with the SFXHTTPConnection::Connect function will be canceled.

Reference

SFXHTTPConnection::Close | SFXHTTPConnection::Connect | SFBWeb | SFBWebResp

SFXHTTPConnection::Cancel

Cancel to connect to the Web server.

[ public ]
Void Cancel(Void);

Description

This function cancels to connect to the Web server using the SFXHTTPConnection::Connect function.

The registered callback with the SFXHTTPConnection::Connect function and the connection timeout timer will be canceled, and the state of this HTTP connection will be restored before calling the SFXHTTPConnection::Connect function, if called.

In general, this function is effective in the STATE_CONNECT state (after calling the SFXHTTPConnection::Connect function and before the notification to the callback function).

This function is called in the SFXHTTPConnection::Close function too.

Reference

SFXHTTPConnection::Close | SFXHTTPConnection::Connect | SFXHTTPConnection::SetTimeoutMillisecond | SFXHTTPConnection::SetTimeoutCallback

SFXHTTPConnection::Clear

Initialize the internal variables of this HTTP connection.

[ public ]
SFCError Clear(Void);

Return value

If succeeds: SFERR_NO_ERROR
If this HTTP connection has not been opened: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function initializes the internal variables of this HTTP connection.

This HTTP connection transits into the STATE_OPEN_UNESTABLISHED state.

Concretely, the following processings will be performed.

Initialize the content of the HTTP request.
Set the HTTP request method to "GET".
Open the internal storage for the HTTP request body to be written.
Initialize the content of the HTTP response.
Transit into the STATE_OPEN_UNESTABLISHED state.

	Caution
	This function will be valid if and only if the state of this HTTP connection is "opened".

Note

	Note
Immediately after this function is executed, connection to the Web server is not established. To establish the connection to the Web server, make the HTTP request of this HTTP connection and call the `SFXHTTPConnection::Connect` function.

Immediately after this function is executed, connection to the Web server is not established.

To establish the connection to the Web server, make the HTTP request of this HTTP connection and call the SFXHTTPConnection::Connect function.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Reference

SFXHTTPConnection::Cancel | SFXHTTPConnection::Open

SFXHTTPConnection::Close

Close this HTTP connection.

[ public ]
Void Close(Void);

Description

This function closes this HTTP connection.

This HTTP connection transits into the STATE_CLOSE state.

Concretely, the following processings will be performed.

Initialize the content of the HTTP request.
Release the SFBWeb / SFBWebResp instance that this HTTP connection contains internally.
Cancel the callback registered into this HTTP connection with the SFXHTTPConnection::Connect function.
Initialize the content of the HTTP response.
Transit into the STATE_CLOSE state.

	Tip
	When suspended, it is necessary to call this function in order to release various resources.

Note

	Note
This function is called in the `SFXHTTPConnection::~SFXHTTPConnection` destructor. This function calls the `SFXHTTPConnection::Cancel` function internally.

This function is called in the SFXHTTPConnection::~SFXHTTPConnection destructor.

This function calls the SFXHTTPConnection::Cancel function internally.

Reference

SFXHTTPConnection::Connect

Connect to the Web server.

[ public ]
SFCError Connect(
    SFXAnsiStringConstRef url   // connect URL
    CallbackSPP spp             // callback function
    VoidPtr reference           // data passed to callback function
);

Return value

If succeeds: SFERR_NO_ERROR
If this HTTP connection has not been opened: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY
If failed: SFERR_FAILED(* This error will be notified to the callback function specified in the argument.)

Description

This function connects to the Web server at the specified URL.

Immediately after this function is called, this HTTP connection will transit into the STATE_CONNECT state. However, when the connection result is notified to the callback function, it will return into the STATE_OPEN state (if succeeds, STATE_OPEN_ESTABLISHED; otherwise, STATE_OPEN_UNESTABLISHED).

Concretely, the following processings will be performed.

Initialize the content of the HTTP response.
If the connection timeout period is not 0, connection timeout processing will be performed(start the timer).
Try to connect to the Web server.
If it succeeds to connect to the Web server, this HTTP connection will be regarded as "established", various information read from the Web server will be set to the HTTP response, and the internal storage for the HTTP response body will be open (the stream to read data from the HTTP response body can be obtained).
Notify the result(error code) of connecting to the Web server to the callback function specified in the argument.
Transit into the STATE_CONNECT state, and then return into the STATE_OPEN. Immediately after this function is called, this HTTP connection will transit into the STATE_CONNECT state. However, when the connection result is notified to the callback function, it will return into the STATE_OPEN state (if succeeds, STATE_OPEN_ESTABLISHED; otherwise, STATE_OPEN_UNESTABLISHED).
If there is no response after the connection timeout period elapses, connection timeout callback will be called( connection timeout processing will be performed).

To cancel before the connection is established, call the SFXHTTPConnection::Cancel function.

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

	Errors while connecting
	The SFERR_FAILED error that represents the error during connecting to the Web server will be notified to the callback function specified in the argument. This error will not be returned by this function.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Example

// define _http, SFXHTTPConnection instance, as member variable
class MyClass {
private:
    SFXHTTPConnection _http;
public:
    Void Start(Void);                               // start HTTP connection
    XALLBACK_DECLARE_SFXHTTPCONNECTION(OnConnect)   // callback function declaration
};

// start the HTTP connection
Void MyClass::Start(Void)
{
    SFCError error(SFERR_NO_ERROR);

    // open the HTTP connection
    if ((error = _http.Open()) == SFERR_NO_ERROR) {   
    
        _http.SetMethod("GET");  // set the HTTP request method to "GET"

        // connect to the Web server
        // the connection result will be notified to the OnConnect function
        if ((error = _http.Connect("http://www.example.com/",
                         XALLBACK_INTERNAL(OnConnect))) == SFERR_NO_ERROR) {
           ...

        }else{

            // if an error occurs, close the HTTP connection
            _http.Close(); 
        }
        
    }

    if (error != SFERR_NO_ERROR) {  

        // if an error occurs
        ...

    }
    return;
}
// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        ...

    }
}

Reference

SFXHTTPConnection::Open | SFXHTTPConnection::Cancel | SFXHTTPConnection::SetTimeoutMillisecond | SFXHTTPConnection::SetTimeoutCallback

SFXHTTPConnection::GetBaseUrl

Get the base URL of HTTP basic authentication.

[ public, const ]
SFXAnsiStringConstRef GetBaseUrl(Void);

Return value

Base URL of HTTP basic authentication

Description

Get the base URL of HTTP basic authentication.

The value which is set by the SFXHTTPConnection::SetAuthorizeData function is gotten.

Reference

SFXHTTPConnection::SetAuthorizeData

SFXHTTPConnection::GetDate

Get the value of the Date field of the HTTP response header.

[ public, const ]
SFXDate GetDate(Void);

Return value

Value of the Date field of the HTTP response header as the SFXDate) instance

Description

This function gets the value of the Date field of the HTTP response header as the SFXDate) instance.

If the Date field of the HTTP response header does not exist or this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, SFXDate(0) will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        // get the value of the Date field of the HTTP response header 
        TRACE("date = %s", _http.GetDate().Format("YYYY/MM/DD hh:mm:ss").GetCString());
        ...
    }
}

Reference

SFXHTTPConnection::Connect | SFXDate

SFXHTTPConnection::GetEncoding

get the value of the Content-Encoding field of the HTTP response header.

[ public, const ]
SFXAnsiStringConstRef GetEncoding(Void);

Return value

Value of the Content-Encoding field of the HTTP response header

Description

This function gets the value of the Content-Encoding field of the HTTP response header.

If this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, the empty string(SFXAnsiString::EmptyInstance()) will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        // get the value of the Content-Encoding field of the HTTP response header
        TRACE("content encoding = %s", _http.GetEncoding().GetCString()); 
        ...
    }
}

Reference

SFXHTTPConnection::Connect | SFXAnsiString

SFXHTTPConnection::GetExpires

Get the value of the Expires field of the HTTP response header.

[ public, const ]
SFXDate GetExpires(Void);

Return value

Value of the Expires field of the HTTP response header as the SFXDate) instance

Description

This function gets the value of the Expires field of the HTTP response header as the SFXDate) instance.

If the Expires field of the HTTP response header does not exist or this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, SFXDate(0) will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        // get the value of the Expires field of the HTTP response header
        TRACE("expires = %s", _http.GetExpires().Format("YYYY/MM/DD hh:mm:ss").GetCString());
        ...
    }
}

Reference

SFXHTTPConnection::Connect | SFXDate

SFXHTTPConnection::GetLastModified

Get the value of the Last-Modified field of the HTTP response header.

[ public, const ]
SFXDate GetLastModified(Void);

Return value

Value of the Last-Modified field of the HTTP response header as the SFXDate) instance

Description

This function gets the value of the Last-Modified field of the HTTP response header as the SFXDate) instance.

If the Last-Modified field of the HTTP response header does not exist or this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, SFXDate(0) will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        // get the value of the Last-Modified field of the HTTP response header
        TRACE("last modified = %s", _http.GetLastModified().Format("YYYY/MM/DD hh:mm:ss").GetCString());
        ...
    }
}

Reference

SFXHTTPConnection::Connect | SFXDate

SFXHTTPConnection::GetLength

Get the value of the Content-Length field of the HTTP response header.

[ public, const ]
SInt32 GetLength(Void);

Return value

Value of the Content-Length field of the HTTP response header

Description

This function gets the value of the Content-Length field of the HTTP response header.

If the Content-Length field of the HTTP response header does not exist or this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, -1 will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        // get the value of the Content-Length field of the HTTP response header
        TRACE("content length = %d", _http.GetLength());
        ...
    }
}

Reference

SFXHTTPConnection::Connect

SFXHTTPConnection::GetMethod

Get the HTTP request method.

[ public, const ]
SFXAnsiStringConstRef GetMethod(Void);

Return value

HTTP request method of this HTTP connection

Description

This function gets the HTTP request method of this HTTP connection set with the SFXHTTPConnection::SetMethod function.

If this HTTP connection is not in the STATE_OPEN state, the empty string(SFXAnsiString::EmptyInstance()) will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        // get the HTTP request method
        TRACE("method = %s", _http.GetMethod().GetCString());
        ...
    }
}

Reference

SFXHTTPConnection::SetMethod | SFXHTTPConnection::Open | SFXAnsiString

SFXHTTPConnection::GetProxyServer

Get the proxy server.

[ public, const ]
SFXSocketAddressConstRef GetProxyServer(Void);

Return value

Proxy server of this HTTP connection

Description

This function gets the proxy server of this HTTP connection set with the SFXHTTPConnection::SetProxyServer function.

If this HTTP connection is not in the STATE_OPEN state, or the proxy server of this HTTP connection has not been set, SFXSocketAddress::EmptyInstance() will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        // get the proxy server
        TRACE("method = %s", _http.GetProxyServer().Get().GetCString());
        ...
    }
}

Reference

SFXHTTPConnection::SetProxyServer | SFXSocketAddress

SFXHTTPConnection::GetRequestContent

Get the SFBSource instance that manages the HTTP request body.

[ public, const ]
SFBSourceSmpConstRef GetRequestContent(Void);

Return value

SFBSource instance that manages the HTTP request body of this HTTP connection

Description

This function gets the SFBSource instance that manages the HTTP request body of this HTTP connection, which is set with the SFXHTTPConnection::SetRequestContent function.

If this HTTP connection is not in the STATE_OPEN state, or the SFBSource instance has not been set, &SFBSourceSmp::EmptyInstance() will be returned.

Reference

SFXHTTPConnection::SetRequestContent | SFBSource

SFXHTTPConnection::GetRequestFlag

Get the HTTP request flag.

[ public, const ]
UInt32 GetRequestFlag(Void);

Return value

HTTP request flag of this HTTP connection

Description

This function gets the HTTP request flag set with the SFXHTTPConnection::SetRequestFlag function.

If this HTTP connection is not in the STATE_OPEN state, 0 will be returned.

Reference

SFXHTTPConnection::SetRequestFlag | SFXHTTPConnection::Open | BREW API IWEB_GetResponse

SFXHTTPConnection::GetRequestHeader

Get the HTTP request header.

[ public, const ]
SFXAnsiStringConstRef GetRequestHeader(
    SFXAnsiStringConstRef key   // field name
);

[ public, const ]
SFXPropertyConstRef GetRequestHeader(Void);

Return value

HTTP request header of this HTTP connection

Description

This function gets the HTTP request header of this HTTP connection set with the SFXHTTPConnection::SetRequestHeader function. It is possible to get the value of the field specified in the argument. If nothing is specified, all of the HTTP request header will be obtained.

If this HTTP connection is not in the STATE_OPEN state, or the specified field of the HTTP request header or itself has not been set, the empty string(SFXAnsiString::EmptyInstance()) or the empty property(SFXProperty::EmptyInstance()) will be returned.

Reference

SFXHTTPConnection::SetRequestHeader | SFXProperty | SFXAnsiString

SFXHTTPConnection::GetResponseContent

Get the SFBSource instance that manages the HTTP response body.

[ public, const ]
SFBSourceSmpConstRef GetResponseContent(Void);

Return value

SFBSource instance that manages the HTTP response body

Description

This function gets the SFBSource instance that manages the HTTP response body of this HTTP connection.

If this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, SFBSourceSmp::EmptyInstance() will be returned.

	Tip
	After this HTTP connection is established, the HTTP response body can be obtained using this function.

	Note
	The `SFXHTTPConnection::GetStreamReader` function gets the stream from the `SFBSource` instance, return value of the `SFXHTTPConnection::GetResponseContent` function.

Reading the HTTP response body

	Reading the HTTP response body
If the HTTP response body is read by using the `SFXHTTPConnection::GetResponseContent` function, the `SFXHTTPConnection::GetStreamReader` function cannot be used. On the contrary, if the HTTP response body is read by using the `SFXHTTPConnection::GetStreamReader` function, the `SFXHTTPConnection::GetResponseContent` function cannot be used.

If the HTTP response body is read by using the SFXHTTPConnection::GetResponseContent function, the SFXHTTPConnection::GetStreamReader function cannot be used.

On the contrary, if the HTTP response body is read by using the SFXHTTPConnection::GetStreamReader function, the SFXHTTPConnection::GetResponseContent function cannot be used.

Reference

SFXHTTPConnection::GetStreamReader | SFBSource | SFXHTTPConnection::Connect

SFXHTTPConnection::GetResponseFlag

Get the HTTP response flag.

[ public, const ]
UInt32 GetResponseFlag(Void);

Return value

HTTP response flag of this HTTP connection

Description

This function gets the HTTP response flag of this HTTP connection.

The HTTP response flag can be represented as logical sum of the following flags:

WEBRESPONSE_REDIRECTED: redirection was handled by IWeb (Unimplemented by BREW's HTTP protocol engine)
WEBRESPONSE_COOKIES:cookies were sent in the request (Unimplemented by BREW's HTTP protocol engine)
WEBRESPONSE_CACHED: retrieved from local cache (no network activity)
WEBRESPONSE_KEEPALIVE: connection kept alive
WEBRESPONSE_HTTP09: got an HTTP0.9 response (so there were no HTTP headers; and the WebRespInfo. nCode == 200 was fabricated
WEBRESPONSE_LOCAL: locally-generated content (no network activity)
WEBRESPONSE_PROXIED: gotten through a proxy
WEBRESPONSE_AUTHBASIC: basic authentication info was sent. (Unimplemented by BREW's HTTP protocol engine)

If this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, 0 will be returned.

Reference

SFXHTTPConnection::SetRequestFlag | SFXHTTPConnection::Connect | SFBWebResp | BREW API IWEBRESP_GetOpt

SFXHTTPConnection::GetResponseHeader

Get the HTTP response header.

[ public, const ]
SFXAnsiStringConstRef GetResponseHeader(
    SFXAnsiStringConstRef key   // field name
);

[ public, const ]
SFXPropertyConstRef GetResponseHeader(Void);

Return value

HTTP response header of this HTTP connection

Description

This function gets the HTTP response header of this HTTP connection set with the SFXHTTPConnection::SetRequestHeader function. It is possible to get the value of the field specified in the argument. If nothing is specified, all of the HTTP response header will be obtained.

If this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, or the specified field of the HTTP response header or itself has not been set, the empty string(SFXAnsiString::EmptyInstance()) or the empty property(SFXProperty::EmptyInstance()) will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    SFXPropertyConstPtr header;
    SInt16 i;

    if (error == SFERR_NO_ERROR) {

        // get the HTTP response header
        header = &_http.GetResponseHeader(); 
        
        // display the HTTP response header information
        for (i = 0; i < header->GetSize(); ++i) {
            TRACE("%s: %s", header->GetKey(i).GetCString(), header->GetValue(i).GetCString());
        }
    }
}

Reference

SFXHTTPConnection::Connect | SFXProperty | SFXAnsiString

SFXHTTPConnection::GetResultCode

Get the HTTP status code.

[ public, const ]
SInt32 GetResultCode(Void);

Return value

HTTP status code of this HTTP connection.

Description

This function gets the HTTP status code of this HTTP connection.

If this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, -1 will be returned.

If this HTTP connection has been established, the return value of this function is same as the nCode field of BREW API's WebRespInfo.

nCode represents either a protocol error code or a *negative* WEB_ERROR (see AEEError.h for codes), use WEB_ERROR_MAP(nCode) to map to AEE error, and WEB_ERROR_SUCCEEDED(nCode) to test for success. A positive number is one that was returned by the server, negative error codes are system errors.

	Note
	For more details on WEB_ERROR, see AEEError.h.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        ...

        if (_http.GetResultCode() == 200) { 

            // if the HTTP status code is 200 (success)

            ...
        
}
    }
}

Reference

SFXHTTPConnection::Connect | BREW API WebRespInfo | BREW API WEB_ERROR_MAP | BREW API WEB_ERROR_SUCCEEDED

SFXHTTPConnection::GetSFBWeb

Get the SFBWeb instance managed internally by this HTTP connection.

[ public, const ]
SFBWebSmpConstRef GetSFBWeb(Void);

Return value

SFBWeb instance managed internally by this HTTP connection.

Description

This function gets the SFBWeb instance managed internally by this HTTP connection.

Reference

SFBWeb | BREW API IWeb

SFXHTTPConnection::GetSFBWebResp

Get the SFBWebResp instance managed internally by this HTTP connection.

[ public, const ]
SFBWebRespSmpConstRef GetSFBWebResp(Void);

Return value

SFBWebResp instance managed internally by this HTTP connection.

Description

This function gets the SFBWebResp instance managed internally by this HTTP connection.

Reference

SFBWebResp | BREW API IWebResp

SFXHTTPConnection::GetState

Get the state of the HTTP/HTTPS connection.

[ public, const ]
StateEnum GetState(Void);

Return value

The state of the HTTP/HTTPS connection (SFXHTTPConnection::StateEnum)

Description

This function gets the state of the HTTP/HTTPS connection (SFXHTTPConnection::StateEnum).

Reference

SFXHTTPConnection::StateEnum

SFXHTTPConnection::GetStreamReader

Get the input stream for reading data from the HTTP response body.

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

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

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null: SFERR_INVALID_PARAM
If this HTTP connection is not in the STATE_OPEN_ESTABLISHED state: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function gets the input stream for reading data from the HTTP response body of this HTTP connection.

If the size argument is specified, the buffer size of the input stream will be fixed with the specified value. Otherwise, the buffer size will be variable and the SFXElasticStreamReader class will be used internally.

	Tip
	You have to use the `SFXBinaryStreamReader`, `SFXAnsiStringStreamReader`, or `SFXWideStringStreamReader` class for the input stream properly depending on the type of data to be read.

Reading the HTTP response body

	Reading the HTTP response body
If the HTTP response body is read by using the `SFXHTTPConnection::GetResponseContent` function, the `SFXHTTPConnection::GetStreamReader` function cannot be used. On the contrary, if the HTTP response body is read by using the `SFXHTTPConnection::GetStreamReader` function, the `SFXHTTPConnection::GetResponseContent` function cannot be used.

If the HTTP response body is read by using the SFXHTTPConnection::GetResponseContent function, the SFXHTTPConnection::GetStreamReader function cannot be used.

On the contrary, if the HTTP response body is read by using the SFXHTTPConnection::GetStreamReader function, the SFXHTTPConnection::GetResponseContent function cannot be used.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN_ESTABLISHED state.

Example

// define _http, the SFXHTTPConnection instance, as the member variable
class MyClass {
private:
    SFXHTTPConnection _http;
    SFXAnsiStringStreamReader _reader;
public:
    Void Start(Void);
    XALLBACK_DECLARE_SFXHTTPCONNECTION(OnConnect)
    XALLBACK_DECLARE_SFXANSISTRINGSTREAMREADER(OnFetch)
};

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        ...

        // if the HTTP status code is 200 (i.e., success)
        if (_http.GetResultCode() == 200) {

            // get the input stream for reading data from the HTTP response body
            if ((error = _http.GetStreamReader(1024, &_reader)) == SFERR_NO_ERROR) {

                // receive data from the HTTP response body onto the input stream actually
                if ((error = _reader.Fetch(XALLBACK_INTERNAL(OnFetch))) == SFERR_NO_ERROR) {

                    ...
                }
            }
        }
        else {

            error = SFERR_INVALID_STATE;
        }
    }

    if (error != SFERR_NO_ERROR) {

        // if an error occurs
       _http.Close();
    }

    return;
}
// callback function notified that data is ready to be received
XALLBACK_IMPLEMENT_SFXANSISTRINGSTREAMREADER(MyClass, OnFetch, error)
{
    if (error == SFERR_NO_ERROR) {

        ...

    }
}

Reference

SFXHTTPConnection::GetStreamWriter

Get the output stream for writing data onto the HTTP request body.

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

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

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null: SFERR_INVALID_PARAM
If this HTTP connection is not in the STATE_OPEN state: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function gets the output stream for writing data onto the HTTP request body of this HTTP connection.

If the size argument is specified, the buffer size of the output stream will be fixed with the specified value. Otherwise, the buffer size will be variable and the SFXElasticStreamWriter class will be used internally.

	Tip
	You have to use the `SFXBinaryStreamWriter`, `SFXAnsiStringStreamWriter`, or `SFXWideStringStreamWriter` class for the output stream properly depending on the type of data to write.

Writing the HTTP response body

	Writing the HTTP response body
If the HTTP response body is set with the `SFXHTTPConnection::SetRequestContent` function, the `SFXHTTPConnection::GetStreamWriter` function cannot be used. On the contrary, if the HTTP response body is written by using the `SFXHTTPConnection::GetStreamWriter` function, the `SFXHTTPConnection::SetRequestContent` function cannot be used.

If the HTTP response body is set with the SFXHTTPConnection::SetRequestContent function, the SFXHTTPConnection::GetStreamWriter function cannot be used.

On the contrary, if the HTTP response body is written by using the SFXHTTPConnection::GetStreamWriter function, the SFXHTTPConnection::SetRequestContent function cannot be used.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Example

// define _http, the SFXHTTPConnection instance, as the member variable
class MyClass {
private:
    SFXHTTPConnection _http;
public:
    Void Start(Void);
    XALLBACK_DECLARE_SFXHTTPCONNECTION(OnConnect)
};

Void MyClass::Start(Void)
{
    SFXAnsiStringStreamWriter writer;
    SFXAnsiString send;
    SFCError error(SFERR_NO_ERROR);

    // open HTTP connection
    if ((error = _http.Open()) == SFERR_NO_ERROR) {

        // data to be sent
        send = "abcdefghijklmnopqrstuvwxyz";

        // get the output stream for writing data onto the HTTP request body.
        if ((error = _http.GetStreamWriter(send.GetLength(), &writer)) == SFERR_NO_ERROR) {

            // write data to the output stream
            if ((error = writer.WriteSFXAnsiString(send)) == SFERR_NO_ERROR) {

                // write data onto the HTTP request body through the output stream actually
                if ((error = writer.Flush()) == SFERR_NO_ERROR) {
                    
                    // set the HTTP request method to "POST"
                    if ((error = _http.SetMethod("POST")) == SFERR_NO_ERROR) {  

                        if ((error = _http.Connect("http://www.example.com", XALLBACK_INTERNAL(OnConnect))) == SFERR_NO_ERROR) {

                            // connect

                            ...

                        }
                    }
                }
            }
        }
    }

    if (error != SFERR_NO_ERROR) {
  
       // if an error occurs
       _http.Close();
    }

    return;
}

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        ....

    }

    return;
}

Reference

SFXHTTPConnection::GetTimeoutMillisecond

Get the connection timeout period. [in milliseconds]

[ public, const ]
UInt32 GetTimeoutMillisecond(Void);

Return value

Connection timeout period [in milliseconds]

Description

This function gets the connection timeout period. [in milliseconds]

Reference

SFXHTTPConnection::SetTimeoutMillisecond | SFXHTTPConnection::SetTimeoutCallback

SFXHTTPConnection::GetTrustMode

Get the SSL trust mode.

[ public, const ]
UInt32 GetTrustMode(Void);

Return value

SSL trust mode

Description

This function gets the SSL trust mode of this HTTP connection set with the SFXHTTPConnection::SetTrustMode function.

If this HTTP connection is not in the STATE_OPEN state, 0 will be returned.

Reference

SFXHTTPConnection::SetTrustMode | SFXHTTPConnection::Open | BREW API ISSL_NegotiateV

SFXHTTPConnection::GetType

Get the value of the Content-Type field of the HTTP response header.

[ public, const ]
SFXAnsiStringConstRef GetType(Void);

Return value

Value of the Content-Type field of the HTTP response header

Description

This function gets the value of the Content-Type field of the HTTP response header of this HTTP connection

If this HTTP connection is not in the STATE_OPEN_ESTABLISHED state, the empty string(SFXAnsiString::EmptyInstance()) will be returned.

Example

// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        // get the Content-Type field of the HTTP response header
        TRACE("content type = %s", _http.GetType().GetCString());

        ...

    }
}

Reference

SFXHTTPConnection::Connect | SFXAnsiString

SFXHTTPConnection::GetUser

Get the user name of HTTP basic authentication.

[ public, const ]
SFXAnsiStringConstRef GetUser(Void);

Return value

User name of HTTP basic authentication

Description

Get the user name of HTTP basic authentication.

The value which is set by the SFXHTTPConnection::SetAuthorizeData function is gotten.

Reference

SFXHTTPConnection::SetAuthorizeData

SFXHTTPConnection::GetUserAgent

Get the user agent of the HTTP request header.

[ public, const ]
SFXAnsiStringConstRef GetUserAgent(Void);

Return value

User agent of this HTTP connection

Description

This function gets the user agent of the HTTP request header of this HTTP connection set with the SFXHTTPConnection::SetUserAgent function.

If this HTTP connection is not in the STATE_OPEN state, the empty string(SFXAnsiString::EmptyInstance()) will be returned.

Reference

SFXHTTPConnection::SetUserAgent | SFXHTTPConnection::Open | SFXAnsiString

LoadCertificate::LoadCertificate

Load a ASN.1/DER form certificate file or buffer.

[ public ]
SFCError LoadCertificate(
    SInt32 kind            // kind of certificate
    SFXPathConstRef path   // file path of certificate
);

[ public ]
SFCError LoadCertificate(
    SInt32 kind                // kind of certificate
    SFXBufferConstRef buffer   // buffer of certificate
);

Argument

kind: kind of certificate: any one of WEBOPT_X509_ROOT_CERT, WEBOPT_X509_LEAF_CERT, and WEBOPT_X509_BRANCH_CERT
path: file path of ASN.1/DER form certificate
buffer: buffer of ASN.1/DER form certificate

Return value

If succeed: SFERR_NO_ERROR
If the HTTP connection is not in the STATE_CLOSE: SFERR_INVALID_STATE
If insuffcient memory: SFERR_NO_MEMORY
If unsupported: SFERR_UNSUPPORTED
Otherwise: SFERR_FAILED

Description

This function loads a file or buffer of ASN.1/DER form certificate.

This function is valid if and only if the HTTP connection is in the STATE_CLOSE.

Example

Load a root certificate file

SFXHTTPConnection http;
SFCError error;

// Load a root certificate before open.
if ((error = http.LoadCertificate(WEBOPT_X509_ROOT_CERT, SFXPath("scradle.der"))) == SFERR_NO_ERROR) {
    if ((error = http.Open()) == SFERR_NO_ERROR) {
        error = http.Connect("https://www.s-cradle.com/example/tabbrowser/", XALLBACK_INTERNAL(OnConnect));
    }
}

Reference

SFBX509Chain::AddCert

SFXHTTPConnection::Open

Open this HTTP connection.

[ public ]
SFCError Open(
    AEECLSID id = AEECLSID_WEB   // ClassID
);

Return value

If succeeds: SFERR_NO_ERROR
If this HTTP connection is not in the STATE_CLOSE state: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function opens this HTTP connection.

This HTTP connection transits into the STATE_OPEN_UNESTABLISHED state.

Concretely, the following processings will be performed.

Create the SFBWeb instance to be managed internally by this HTTP connection.
Initialize the content of the HTTP request.
Set the HTTP request method to "GET".
Open the internal storage for the HTTP request body to be written.
Initialize the content of the HTTP response.
Transit into the STATE_OPEN_UNESTABLISHED state.

Note

	Note
Immediately after this function is executed, connection to the Web server is not established. To establish the connection to the Web server, make the HTTP request of this HTTP connection and call the `SFXHTTPConnection::Connect` function.

Immediately after this function is executed, connection to the Web server is not established.

To establish the connection to the Web server, make the HTTP request of this HTTP connection and call the SFXHTTPConnection::Connect function.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_CLOSE state.

Example

// define _http, the SFXHTTPConnection instance, as the member variable
class MyClass {
private:
    SFXHTTPConnection _http;
public:
    Void Start(Void);
};

// start HTTP connection
Void MyClass::Start(Void)
{
    SFCError error(SFERR_NO_ERROR);

    // open the HTTP connection
    if ((error = _http.Open()) == SFERR_NO_ERROR) {

        ...
    }

    if (error != SFERR_NO_ERROR) {

        // if an error occurs
        ...
    }
    return;
}

Reference

SFXHTTPConnection::Connect

SFXHTTPConnection::SetAuthorizeData

Set the information of HTTP basic authentication.

[ public ]
SFCError SetAuthorizeData(
    SFXAnsiStringConstRef user     // user name
    SFXAnsiStringConstRef passwd   // password
    SFXAnsiStringConstRef url      // base URL of HTTP basic authentication
);

Argument

user: Specify a user name.
passwd: Specify a password.
url: Specify a base URL. Pages which start with this URL will be authenticated.

Return value

If succeed: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY
If the HTTP connection is not in the STATE_OPEN: SFERR_INVALID_STATE

Description

This function sets the information of HTTP basic authentication.

After calling this fuction, pages whose URL starts with specified url argument will be accessed with basic authentication header.

This function is valid if and only if the HTTP connection is in the STATE_OPEN.

To unset the basic authentication information, call this function with specifying empty strings.

	Note
	If a return value is not SFERR_NO_ERROR, the basic authentication is not performed.

Reference

SFXHTTPConnection::Open

SFXHTTPConnection::SetMethod

Set the HTTP request method.

[ public ]
SFCError SetMethod(
    SFXAnsiStringConstRef param   // method (character string)
);

Return value

If succeeds: SFERR_NO_ERROR
If this HTTP connection is not in the STATE_OPEN state: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function sets he HTTP request method of this HTTP connection.

As the method argument, the methods supported by the BREW IWeb interface such as "GET", "POST", "HEAD" can be specified.

Default: "GET"

The value set by the this function will be effective until the SFXHTTPConnection::Close or SFXHTTPConnection::Clear function is called.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Example

// define _http, SFXHTTPConnection instance, as member variable
class MyClass {
private:
    SFXHTTPConnection _http;
public:
    Void Start(Void);
};

// start HTTP connection
Void MyClass::Start(Void)
{
    SFCError error(SFERR_NO_ERROR);

    // open HTTP connection
    if ((error = _http.Open()) == SFERR_NO_ERROR) {

        // set HTTP request method to "GET"
        _http.SetMethod("GET");
        ...
    }

    if (error != SFERR_NO_ERROR) {
        // if an error occurs
        ...
    }
    return;
}

Reference

SFXHTTPConnection::SetProxyServer

Set the proxy server.

[ public ]
SFCError SetProxyServer(
    SFXSocketAddressConstRef param   // proxy server
);

Return value

If succeeds: SFERR_NO_ERROR
If this HTTP connection is not in the STATE_OPEN state: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function sets the proxy server (SFXSocketAddress) of this HTTP connection to the specified value.

The value set by the this function will be effective until the SFXHTTPConnection::Close or SFXHTTPConnection::Clear function is called.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Example

// define _http, SFXHTTPConnection instance, as member variable
class MyClass {
private:
    SFXHTTPConnection _http;
public:
    Void Start(Void); 
};

// start HTTP connection
Void MyClass::Start(Void)
{
    SFCError error(SFERR_NO_ERROR);

    // open HTTP connection
    if ((error = _http.Open()) == SFERR_NO_ERROR) {

        // set proxy server
        error = _http.SetProxyServer(SFXSocketAddress("exampleproxy.co.jp:8080"));
        ...
    }

    if (error != SFERR_NO_ERROR) {  
        // if an error occurs
        ...
    }
    return;
}

Reference

SFXHTTPConnection::GetProxyServer | SFXHTTPConnection::Open | SFXHTTPConnection::Close | SFXHTTPConnection::Clear | SFXSocketAddress

SFXHTTPConnection::SetRequestContent

Set the HTTP request body of this HTTP connection to the specified storage or source.

[ public ]
SFCError SetRequestContent(
    SFXFileConstRef file   // file storage to set to the HTTP request body
);

[ public ]
SFCError SetRequestContent(
    SFXMemoryConstRef memory   // memory storage to set to the HTTP request body
);

[ public ]
SFCError SetRequestContent(
    SFXStorageConstRef storage   // storage to set to the HTTP request body
    SInt32 length                // length of the storage
);

[ public ]
SFCError SetRequestContent(
    SFBSourceSmpConstRef source   // source to set to the HTTP request body
    SInt32 length                 // length of the source
);

Return value

If succeeds: SFERR_NO_ERROR
If argument is null: SFERR_INVALID_PARAM
If this HTTP connection is not in the STATE_OPEN state or the specified storage or SFBSource instance has not been opened: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function sets the HTTP request body of this HTTP connection to the specified storage or source.

If only the file or memory storage is specified in the argument, its total storage length will be automatically set.

When the length argument is specified, data of the specified length from the current read / write pointer of the storage or source will be set to the HTTP request body of this HTTP connection.

Tip

	Tip
If a file storage(`SFXFile`) is set with the `SFXHTTPConnection::SetRequestContent` function, data will be sent directly to the network from the file storage. As a result, big data can be sent. When data is sent with the `SFXHTTPConnection::GetStreamWriter` function, the HTTP request body is made in the heap befre sent. As a result, the data size that can be sent will depends on the memory size equipped with the handset device.

If a file storage(SFXFile) is set with the SFXHTTPConnection::SetRequestContent function, data will be sent directly to the network from the file storage. As a result, big data can be sent.

When data is sent with the SFXHTTPConnection::GetStreamWriter function, the HTTP request body is made in the heap befre sent. As a result, the data size that can be sent will depends on the memory size equipped with the handset device.

Writing the HTTP response body

	Writing the HTTP response body
If the HTTP response body is set with the `SFXHTTPConnection::SetRequestContent` function, the `SFXHTTPConnection::GetStreamWriter` function cannot be used. On the contrary, if the HTTP response body is written by using the `SFXHTTPConnection::GetStreamWriter` function, the `SFXHTTPConnection::SetRequestContent` function cannot be used.

If the HTTP response body is set with the SFXHTTPConnection::SetRequestContent function, the SFXHTTPConnection::GetStreamWriter function cannot be used.

On the contrary, if the HTTP response body is written by using the SFXHTTPConnection::GetStreamWriter function, the SFXHTTPConnection::SetRequestContent function cannot be used.

The value set by the this function will be effective until the SFXHTTPConnection::Close or SFXHTTPConnection::Clear function is called.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

	Note
	The `SFXHTTPConnection::SetRequestContent` function is effective in SophiaFramework UNIVERSE 5.1.11 or above.

Reference

SFXHTTPConnection::SetRequestFlag

Set the HTTP request flag.

[ public ]
SFCError SetRequestFlag(
    UInt32 param   // flag
);

Return value

If succeeds: SFERR_NO_ERROR
If this HTTP connection is not in the STATE_OPEN state: SFERR_INVALID_STATE

Description

This function sets the HTTP request flag of this HTTP connection to the specified value.

	Note
	This HTTP request flag will be internally passed to the `IWEB_GetResponse` function.

Concretely, the logical sum of the following flags are set as the flag argument.

WEBREQUEST_REDIRECT: handle redirection invisibly, if possible (Unimplemented by BREW's HTTP protocol engine)
WEBREQUEST_NOCOOKIES: do not process cookies; pass headers through to caller (Unimplemented by BREW's HTTP protocol engine, but it this behaviour is the default)
WEBREQUEST_NOCACHE: send "Pragma: no-cache" to proxy (if proxying) (Unimplemented by BREW's HTTP protocol engine)
WEBREQUEST_NOKEEPALIVE: disable keep-alives; By default, the HTTP engine sends a "Connection: Keep-Alive" header. If this flag is set, the header is not sent, nor will the HTTP engine keep the socket open even if the server sends Keep-Alive. Specifying a "Connection: " header of your own may have unpredictable results, since the HTTP engine does not parse headers passed in the request.
WEBREQUEST_FORCENEWCONN: force a new connection
WEBREQUEST_NOWAITCONN: don't wait for reusable connection, force new
WEBREQUEST_HTTPBOGUSCRLF: append an extra CRLF to HTTP request bodies to work around a CERN webserver bug

The value set by the this function will be effective until the SFXHTTPConnection::Close or SFXHTTPConnection::Clear function is called.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Reference

SFXHTTPConnection::GetRequestFlag | SFXHTTPConnection::Open | SFXHTTPConnection::Close | SFXHTTPConnection::Clear | BREW API IWEB_GetResponse

SFXHTTPConnection::SetRequestHeader

Set the HTTP request header.

[ public ]
SFCError SetRequestHeader(
    SFXAnsiStringConstRef key     // header name
    SFXAnsiStringConstRef value   // header value
);

Return value

If succeeds: SFERR_NO_ERROR
If header name is User-Agent, or Content-Length, or Connection: SFERR_INVALID_PARAM
If this HTTP connection is not in the STATE_OPEN state: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function sets the HTTP request header to the specified (key, value) pair.

If this function is called several times with the same key, all the requests are stored together and then will be sent at a time.

The values set by the SFXHTTPConnection::SetRequestHeader function will be destroyed when the SFXHTTPConnection::Close function is called or the connection to the Web server is established.

The value set by the this function will be effective until the SFXHTTPConnection::Close or SFXHTTPConnection::Clear function is called.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Reference

SFXHTTPConnection::SetTimeoutCallback

Set the connection timeout callback.

[ public ]
Void SetTimeoutCallback(
    SFXCallback::CallbackSPP spp   // callback
    VoidPtr reference              // data passed to callback
);

Description

This function sets the connection timeout callback, which will be called in case there is no response from the server when the connection timeout period elapses from the communication startup.

If no callback is set, by default, the SFXHTTPConnection::OnTimeoutDefault function will be registered as a connection timeout callback.

The SFXHTTPConnection::OnTimeoutDefault function cancels the communication by calling the SFXHTTPConnection::Cancel function as in the internal implementation code below.

/*private */XALLBACK_IMPLEMENT_SFXTIMER(SFXHTTPConnection, OnTimeoutDefault)
{
    Cancel();
    return;
}// XALLBACK_IMPLEMENT_SFXTIMER(SFXHTTPConnection, OnTimeoutDefault)

	Note
	The connection timeout period is set by using the `SFXHTTPConnection::SetTimeoutMillisecond` function.

Reference

SFXHTTPConnection::SetTimeoutMillisecond | SFXHTTPConnection::Cancel

SFXHTTPConnection::SetTimeoutMillisecond

Set the connection timeout period to the specified value. [in milliseconds]

[ public ]
Void SetTimeoutMillisecond(
    UInt32 msec   // value to set
);

Description

This function sets the connection timeout period to the specified value. [in milliseconds]

Defualt: 0 (Timeout processing will not be performed.)

In case there is no response from the server when the connection timeout period elapses from the communication startup, the connection timeout callback registered by calling the SFXHTTPConnection::SetTimeoutCallback function will be called.

	Note
	If the connection timeout period is set to 0, timeout processing will not be performed.

Reference

SFXHTTPConnection::GetTimeoutMillisecond | SFXHTTPConnection::SetTimeoutCallback

SFXHTTPConnection::SetTrustMode

Set the SSL trust mode.

[ public ]
SFCError SetTrustMode(
    UInt32 param   // SSL trust mode
);

Return value

If succeeds: SFERR_NO_ERROR
If this HTTP connection is not in the STATE_OPEN state: SFERR_INVALID_STATE

Description

This function sets the SSL trust mode of this HTTP connection to the specified value(effective only if this HTTP connection is HTTPS).

The value set by this function is effective until the SFXHTTPConnection::Close or SFXHTTPConnection::Clear function is called.

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

To avoid this error, call the SFXHTTPConnection::Close or SFXHTTPConnection::Clear function once, set the SSL trust mode, and then call the SFXHTTPConnection::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
	For more details, see `BREW API ISSL_NegotiateV` in the BREW API Reference

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Example

// define _http, SFXHTTPConnection instance, as member variable
class MyClass {
private:
    SFXHTTPConnection _http;
public:
    Void Start(Void);   
    XALLBACK_DECLARE_SFXHTTPCONNECTION(OnConnect) 
};

// start HTTP connection
Void MyClass::Start(Void)
{
    SFCError error(SFERR_NO_ERROR);

    // open HTTP connection
    if ((error = _http.Open()) == SFERR_NO_ERROR) {
    
        // set SSL trust mode
        _http.SetTrustMode(SSL_TRUST_MODE_FAIL);
        
        // connect to Web server
        if ((error = _http.Connect("https://www.example.com/",
                         XALLBACK_INTERNAL(OnConnect))) == SFERR_NO_ERROR) {
           ...
        }else{
            // if an error occurs
            _http.Close();
        }
        
    }

    if (error != SFERR_NO_ERROR) {  
        // if an error occurs
        ...
    }
    return;
}
// callback function notified of the connection result
XALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        ...

    }
}

Reference

SFXHTTPConnection::SetUserAgent

Set the user agent.

[ public ]
SFCError SetUserAgent(
    SFXAnsiStringConstRef param   // user agent
);

Return value

If succeeds: SFERR_NO_ERROR
If this HTTP connection is not in the STATE_OPEN state: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

This function sets the user agent of this HTTP connection to the specified value.

The value set by the this function will be effective until the SFXHTTPConnection::Close or SFXHTTPConnection::Clear function is called.

	Note
	This function is valid if and only if this HTTP connection is in the STATE_OPEN state.

Reference

SFXHTTPConnection::GetUserAgent | SFXHTTPConnection::Open | SFXHTTPConnection::Close | SFXHTTPConnection::Clear | SFXAnsiString

SFXHTTPConnection::CallbackSPP

Type that represents the callback function.

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

Description

SFXHTTPConnection::CallbackSPP is the type of the callback function for the SFXHTTPConnection class.

The result of the HTTP communication is notified to this callback function.

The 1st argument is an error code, and the 2nd argument is a parameter for the callback function(in general, instance of SFXHTTPConnection class).

Reference

SFXHTTPConnection::Connect

SFXHTTPConnection::StateEnum

Enumeration which represents the state of the HTTP/HTTPS connection.

enum StateEnum {
    STATE_CLOSE = 0,    // the state that the HTTP connection has not initialized
    STATE_OPEN,         // the state before connecting to the Web server and after connection to the Web server is established.
    STATE_CONNECT       // the state during connecting to the Web server
};
SFMTYPEDEFTYPE(StateEnum)

Description

The HTTP connection(SFXHTTPConnection instance) transits among three kinds of states below(strictly, four kinds of them).

Table 193. State of the HTTP connection

State of the HTTP connection Description

State of the HTTP connection	Description
`STATE_CLOSE`	This state represents the state that the HTTP connection has not been initialized. After the `SFXHTTPConnection` instance is created (i.e., the `SFXHTTPConnection::SFXHTTPConnection` constructor is executed) or the `SFXHTTPConnection::Close` function is executed, the HTTP connection will transit into the STATE_CLOSE state.
`STATE_OPEN(STATE_OPEN_UNESTABLISHED/STATE_OPEN_ESTABLISHED)`	This state represents the states before connecting to the Web server and after connection to the Web server is established. In both of the above states, the HTTP connection has been initialized. For convenience, in this reference, these two states are called STATE_OPEN_UNESTABLISHED and STATE_OPEN_ESTABLISHED respectively. (STATE_OPEN represents the state that these two states are put together). If the `SFXHTTPConnection::Open` function is called in the STATE_CLOSE state, the HTTP connection will transit into the STATE_OPEN_UNESTABLISHED state. And, if the `SFXHTTPConnection::Clear` function is called in the STATE_OPEN_ESTABLISHED state, the HTTP connection will transit into the STATE_OPEN_UNESTABLISHED state.
`STATE_CONNECT`	This state represents the state during connecting to the Web server. If the `SFXHTTPConnection::Connect` function is called in the STATE_OPEN state, the HTTP connection will transit into the STATE_CONNECT state. However, when the result of this connection is passed to the callback function specified in this function, it will return into the STATE_OPEN state again(in case of success, STATE_OPEN_ESTABLISHED; otherwise, STATE_OPEN_UNESTABLISHED).

STATE_CLOSE

This state represents the state that the HTTP connection has not been initialized.

STATE_OPEN(STATE_OPEN_UNESTABLISHED/STATE_OPEN_ESTABLISHED)

This state represents the states before connecting to the Web server and after connection to the Web server is established. In both of the above states, the HTTP connection has been initialized.

STATE_CONNECT

This state represents the state during connecting to the Web server.

Refrence

SFXHTTPConnection::GetState | SFXHTTPConnection::Connect

SFXHTTPConnection::GetPassword

Get the password of HTTP basic authentication.

[ public, const ]
SFXAnsiStringConstRef GetPassword(Void);

Return value

Password of HTTP basic authentication

Description

Get the password of HTTP basic authentication.

The value which is set by the SFXHTTPConnection::SetAuthorizeData function is gotten.

Reference

SFXHTTPConnection::SetAuthorizeData