SYSSwitchToBrowserForCallbackURL

Syntax

#include <cafe/sysapp.h>

typedef struct SysStandardArgsIn
{
    /** Performs an application jump, and, upon return from the jump destination, specifies the data available with SYSGetArguments.
     *  This data is used to determine which sequence the jump occurred and returned from.
     */
    const char *    cp_Anchor;
    /** Specifies the size of the data block specified above. (4096 bytes maximum)
     */
    u32             anchorSize;
} SysStandardArgsIn;

typedef struct SysBrowserArgsInForCallbackURL
{
    SysStandardArgsIn   stdIn;      ///< Common standard arguments.

    /** Specifies the pointer to the URL string.
     * The URL string must be a NULL-terminated string starting with either http:// or  https://.
     * The maximum size, including the scheme at the start (and not including the terminator code) is 1023 characters.
     * When including characters that cannot be used in a URI, use percent encoding in advance.
     */
    const char *        cp_URL;

    /** Specifies the size of the URL string. Specify a size that includes a terminating character. 
     */ 
    u32                 urlSize;

    /** Specifies the pointer to the callback URL string. Limitations are the same as for the URL string.
     */
    const char *        cp_CallbackURL;

    /** Specifies the size of the callback URL string. Specify a size that includes a terminating character. 
     */
    u32                 callbackUrlSize;

    /** Flag indicating whether HBM is prohibited in the Internet Browser. (When callbackURL is specified, it is always in an HBM-prohibited state.)
    */
    BOOL                hbmDisable;
} SysBrowserArgsInForCallbackURL;

s32 SYSSwitchToBrowserForCallbackURL( const SysBrowserArgsInForCallbackURL *cp_Args );

Parameters

cp_Args The cp_URL member should be set to the URL that the Internet Browser will open.

Return Values

SYS_ERROR_NONE The function completed successfully.
SYS_ERROR_SERIALIZE_ANCHOR_SIZE_MAX The cp_Anchor size is larger than the maximum size allowed.
SYS_ERROR_SERIALIZE_URL_SIZE_MAX The cp_URL size is greater than 1024.

Description

Switches to the Internet browser with the specified callback mode. The callback mode is a feature that lets the application delegate operations such as authentication of web services to the Internet browser. Control returns to the caller when the URL specified in callbackURL is a prefix match for the URL that is opened. (The entire URL is returned at this time.) When this function is called, the RELEASE_FOREGROUND message is sent from the system. Subsequently, the current process is shifted to the background and switched to the Internet browser process by calling the OSReleaseForeground function.

Assuming the following:

pass only up to http://example.com/auth_success.html as the callbackURL and get the authenticated token from the URL string that is returned.

Use the SYSGetArguments function to get the URL from the return value.

This function is specifically designed for authentication at the target URL. None of the Internet Browser features (such as bookmarks, search, URL input, or the HOME Menu) can be used in the Internet Browser that is switched to.

Notes

You can control the browser, for example by using JavaScript to close the browser after it has been displayed. Below is the explanation of how to close the browser and other browser controls.

  1. How to closer the browser using JavaScript
  2. After the Internet Browser is started with the SYSSwitchToBrowserForCallbackURL function, if the following conditions are met while browsing, the Internet Browser is terminated and the control returns to the calling application.

    Here, if you use JavaScript to put the Internet Browser to the following state, you can close the Internet Browser.

  3. Tabs in the Internet Browser
  4. If the Internet Browser is started in the special startup mode, the previously opened tabs are not restored, and only the web page specified by URL is opened. However, if you use window.open or other methods to open another browser window from that page, a tab will be added.

  5. Measures against URL being changed
  6. If the Internet Browser is started with the SYSSwitchToBrowserForCallbackURL function, the address bar is displayed but it is grayed out so users cannot change it. The beginning portion of the URL that is shown in the address bar is visible to users, but users cannot see the remainder of the URL that does not fit in the address bar.

Do Not Call From

Background Do not call this function from the background.
Multiple threads This function is not thread-safe.

Revision History

2015/04/09 Changed the callback mode to the special startup mode. Added Notes.
2014/02/14 Initial version.


CONFIDENTIAL