Inheritance diagram

Description

The SFXHTTPConnection class provides the functions necessary for the HTTP/HTTPS communication that are 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.

How to use the HTTP/HTTPS connection

// define _http, instance of SFXHTTPConnection class, as member variable
class MyClass {
private:
    SFXHTTPConnection _http;
    SFXAnsiStringStreamReader _reader;
    SFXAnsiString _receivedString;
public:
    Void Start(Void);
    CALLBACK_DECLARE_SFXHTTPCONNECTION(OnConnect)
    CALLBACK_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
        // connection establishment will be notified to OnConnect function
        if ((error = _http.Connect("http://www.example.com/",
                         CALLBACK_FUNCTION(OnConnect))) == SFERR_NO_ERROR) {
#else
        // HTTPS connection
        // set verification mode if needed
        // connection establishment will be notified to OnConnect function
        _http.SetTrustMode(SSL_TRUST_MODE_FAIL);
        if ((error = _http.Connect("https://www.example.com/",
                         CALLBACK_FUNCTION(OnConnect))) == SFERR_NO_ERROR) {
#endif
            ...
        }
    }

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

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    SFXPropertyConstPtr header;
    SInt16 i;

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

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

        
        // get 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 receiving data
            if ((error = _http.GetStreamReader(1024, &_reader))
                == SFERR_NO_ERROR) {

                // receive data actually (completion of receiving data will be notified to OnFetch function)
                if ((error = _reader.Fetch(CALLBACK_FUNCTION(OnFetch)))
                    == SFERR_NO_ERROR) {
                    ...
                }
            }
        }
        else {
            error = SFERR_INVALID_STATE;
        }
    }

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

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

    if (error == SFERR_NO_ERROR) {

        // get data from input stream
        if ((error = _reader.ReadSFXAnsiString(&string)) == SFERR_NO_ERROR) {

            // combine fragmented data
            if ((error = _receivedString.Add(string)) == SFERR_NO_ERROR) {

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

                    // display all data received
                    TRACE("--------");
                    TRACE("%s", _receivedString.GetCString());
                    TRACE("--------");

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

                    // receive data actually ( completion of receiving data will be notified to OnFetch function )
                    error = _reader.Fetch(CALLBACK_FUNCTION(OnFetch));
                }
            }
        }
    }

    if (error != SFERR_NO_ERROR) {
        // if error occurs
        _reader.Release();
        _http.Close();
    }
    return;
}

Limitation

BREW 2.0 IWeb Interface limitation: data exceeding 1536 bytes cannot be sent.

BREW 2.0 IWeb Interface limitation: data exceeding 64K bytes cannot be sent.

Reference

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

Member

Description

Initialize member variables

Description

If the connection is in the open status, the SFXHTTPConnection::Close function will be called internally, and all the resources are released.

Reference

SFXHTTPConnection::Close

Return value

Reference

SFXHTTPConnection::Cancel

Description

Terminate the connection to the Web server, and release all the resources that are used internally.

Reference

SFXHTTPConnection::Cancel

Return value

Description

Destroy the streams obtained by the SFXHTTPConnection::GetStreamReader and SFXHTTPConnection::GetStreamWriter functions and the HTTP response header obtained in the previous connection.

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

Example

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

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

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

        // connect to Web server
        // connection establishment will be notified to OnConnect function
        if ((error = _http.Connect("http://www.example.com/",
                         CALLBACK_FUNCTION(OnConnect))) == SFERR_NO_ERROR) {
           ...
        }else{
            // if error occurs, close HTTP connection
            _http.Close(); 
        }
        
    }

    if (error != SFERR_NO_ERROR) {  
        // if error occurs
        ...
    }
    return;
}
// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {
        ...
    }
}

Reference

SFXHTTPConnection::Open

Return value

Parse the Date field of HTTP response header, and return it as an instance of SFXDate class.

Return 0 (instance of SFXDate class initialized with 0) if the HTTP response header dose not include the Date field.

Description

The SFXHTTPConnection::GetDate function returns the date and time as the number of seconds since January 6, 1980 00:00:00 (GMT). The date and time in this format is handled in the BREW helper functions: the GETJULIANDATE function and the GETTIMESECONDS function.

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

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

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

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

Return value

Parse the Expires field of HTTP response header, and return it as an instance of SFXDate class.

Return 0 (instance of SFXDate class initialized with 0) if if the HTTP response header dose not include the Expires field.

Description

The SFXHTTPConnection::GetExpires function returns the date and time as the number of seconds since January 6, 1980 00:00:00 (GMT). The date and time in this format is handled in the BREW helper functions: the GETJULIANDATE function and the GETTIMESECONDS function.

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

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

Return value

Parse the Last-Modified field of HTTP response header, and return it as an instance of SFXDate class.

Return 0 (instance of SFXDate class initialized with 0) if the HTTP response header dose not include the Last-Modified field.

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

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

Return value

Return the Content-Length field of HTTP response header. Return -1 if failed.

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

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

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

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

Reference

SFXHTTPConnection::SetMethod

Description

The proxy server is set as an instance of the SFXSocketAddress class.

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

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

Reference

SFXHTTPConnection::SetProxyServer

Description

	Caution
	When using the SFXHTTPConnection::GetRequestContent function, both the SFXHTTPConnection::GetStreamWriter function and SFXHTTPConnection::GetStreamReader function cannot be used.

Reference

SFXHTTPConnection::SetRequestContent

Return value

Detailed information on receiving the HTTP request can be obtained as the following logical sum of flags:

Description

The SFXHTTPConnection::GetRequestFlag function returns the detailed communication settings which are passed to IWEB_GetResponse function used during communication internally.

Reference

BREW API IWEB_GetResponse | SFXHTTPConnection::SetRequestFlag

Return value

Return an empty property (empty string) if the connection has not been established.

Reference

SFXHTTPConnection::SetRequestHeader

Description

	Caution
	When using SFXHTTPConnection::GetResponseContent function, both the SFXHTTPConnection::GetStreamWriter function and SFXHTTPConnection::GetStreamReader function cannot be used.

Return value

Detailed information on receiving the HTTP response can be obtained as the following logical sum of flags:

Description

The SFXHTTPConnection::GetResponseFlag function returns the return value of the IWEBRESP_GetOpt function where WEBOPT_FLAGS is specified in the IWebResp interface internally.

Reference

BREW API IWEBRESP_GetOpt | SFXHTTPConnection::SetRequestFlag

Return value

Return an empty string if the connection has not been established.

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    SFXPropertyConstPtr header;
    SInt16 i;

    if (error == SFERR_NO_ERROR) {

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

Return value

Return the HTTP status code. Return -1 if the connection is not established.

Description

The SFXHTTPConnection::GetResultCode returns a negative value like the nCode field of BREW API WebRespInfo when a communication error occurs.

The error code of BREW can be obtained by passing the return value of this function to WEB_ERROR_MAP().

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {
        ...
        if (_http.GetResultCode() == 200) { 
        // if HTTP status code is 200 (success)
            ...
        }
    }
}

Reference

SFXHTTPConnection::GetSFBWebResp

Reference

SFXHTTPConnection::GetSFBWeb

Return value

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.

	Caution
	When using the SFXHTTPConnection::GetStreamReader function, the SFXHTTPConnection::GetRequestContent, SFXHTTPConnection::GetResponseContent, and SFXHTTPConnection::SetRequestContent functions cannot be used.

Example

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

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {
        ...
        // if HTTP status code is 200 (success)
        if (_http.GetResultCode() == 200) {

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

                // receive data from HTTP connection into the stream actually
                if ((error = _reader.Fetch(CALLBACK_FUNCTION(OnFetch))) == SFERR_NO_ERROR) {
                    ...
                }
            }
        }
        else {
            error = SFERR_INVALID_STATE;
        }
    }

    if (error != SFERR_NO_ERROR) {
        // if error occurs
       _http.Close();
    }
    return;
}
// callback function notified of completion of receiving data actually
CALLBACK_IMPLEMENT_SFXANSISTRINGSTREAMREADER(MyClass, OnFetch, error)
{
    if (error == SFERR_NO_ERROR) {
        ...
    }
}

Reference

SFXHTTPConnection::GetStreamWriter | SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader

Return value

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

	Caution
	When using the SFXHTTPConnection::GetStreamWriter function, the SFXHTTPConnection::GetRequestContent function, SFXHTTPConnection::GetResponseContent function, and SFXHTTPConnection::SetRequestContent function cannot be used.

Example

// define _http, instance of SFXHTTPConnection class, as member variable
class MyClass {
private:
    SFXHTTPConnection _http;
public:
    Void Start(Void);
    CALLBACK_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 output stream for sending data
        if ((error = _http.GetStreamWriter(send.GetLength(), &writer)) == SFERR_NO_ERROR) {

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

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

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

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

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {
        ....
    }
    return;
}

Reference

SFXHTTPConnection::GetStreamReader | SFXBinaryStreamWriter | SFXAnsiStringStreamWriter | SFXWideStringStreamWriter

Description

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

	Note
	Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXHTTPConnection::SetTrustMode

Example

// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

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

Reference

SFXHTTPConnection::SetUserAgent

Return value

Description

Initialize the HTTP connection. Internally generate the instance of SFBWeb class.

Example

// define _http, SFXHTTPConnection class instance, as member variable of class
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) {
        ...
    }

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

Reference

SFXHTTPConnection::Connect

Return value

Description

The value set by the SFXHTTPConnection::SetMethod function is effective until the SFXHTTPConnection::Close function is called.

The methods supported by the BREW IWeb interface are available in the SFXHTTPConnection::SetMethod function: "GET", "POST", "HEAD" etc. can be used.

If setting of the HTTP request method is obmitted, the "GET" method is used by default.

Example

// define _http, instance of SFXHTTPConnection class, 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 error occurs
        ...
    }
    return;
}

Reference

SFXHTTPConnection::GetMethod

Return value

Description

Set the proxy server of SFXSocketAddress class.

Example

// define _http, instance of SFXHTTPConnection class, 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 error occurs
        ...
    }
    return;
}

Reference

SFXHTTPConnection::GetProxyServer

Return value

Description

	Caution
	When using the SFXHTTPConnection::SetRequestContent function, the SFXHTTPConnection::GetStreamWriter function and SFXHTTPConnection::GetStreamReader function cannot be used.

Reference

SFXHTTPConnection::GetRequestContent

Return value

Reference

SFXHTTPConnection::GetRequestFlag

Return value

Description

If the SFXHTTPConnection::SetRequestHeader 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.

Reference

SFXHTTPConnection::GetRequestHeader

Return value

Description

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

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

To avoid this error, call the SFXHTTPConnection::Close 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:

	Note
	Detailed information: ISSL_NegotiateV in the BREW API Reference

Example

// define _http, instance of SFXHTTPConnection class, as member variable
class MyClass {
private:
    SFXHTTPConnection _http;
public:
    Void Start(Void);   
    CALLBACK_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("http://www.example.com/",
                         CALLBACK_FUNCTION(OnConnect))) == SFERR_NO_ERROR) {
           ...
        }else{
            // if error occurs
            _http.Close();
        }
        
    }

    if (error != SFERR_NO_ERROR) {  
        // if error occurs
        ...
    }
    return;
}
// callback function notified of connection establishment
CALLBACK_IMPLEMENT_SFXHTTPCONNECTION(MyClass, OnConnect, error)
{
    if (error == SFERR_NO_ERROR) {

        ...

    }
}

Reference

BREW API ISSL_NegotiateV | SFXHTTPConnection::GetTrustMode | SFXHTTPConnection::Connect | SFXHTTPConnection::Close

Return value

Reference

SFXHTTPConnection::GetUserAgent

Description

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

The result of the HTTP/HTTPS 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