PtWebClient

Widget for displaying web pages

Class hierarchy:

PtWidget → PtBasic → PtContainer → PtClient → PtWebClient

For more information, see the diagram of the widget hierarchy.

PhAB icon:

Public header:

<photon/PtWebClient.h>

Description:

You can use the PtWebClient widget to start, interact, and control a web server, such as Voyager or NetFront. PtWebClient also provides a user-defined area within your application for the server to format and display web pages. Your application controls the server by setting widget resources. The server communicates status information and user interaction back to the application using the widget callbacks.

PtWebClient transparently supports the version of HTML that the server supports. For more information about the Voyager and NetFront web servers, see the vserver and netfront documentation in the QNX^® Momentics^® 6.3.0 Web Browser Technology Development Kit Release Notes.

---

The PtWebClient widget can interact with a web server only on self-hosted systems. On Windows hosts you can use the widget in a PhAB project, but it won't display content until run on a target.

---

Starting the server

Start the server initially by setting the Pt_ARG_WEB_SERVER resource.

Typically, the PtWebClient widget is in a PhAB application, and its Pt_ARG_WEB_SERVER resource is NULL.

You can set the Pt_ARG_WEB_SERVER resource to either:

• the name of a web server profile
  Or:
• a web server command and any command-line options

If you set this resource to a profile name (for example, online), the widget searches the web server profile files for a match. If a match is found, the widget starts the web server and client name found in the profile; the Pt_ARG_CLIENT_NAME is ignored (since it is already in the profile). If the profile is not found, the widget assumes the resource is the command, including path if required, for the web server's executable.

If you start the profile name with the @ character, there is no profile lookup. Instead, the web client widget discards the @, and uses the remaining string as the command line (including path and options) for starting the server.

To start the current online web server, do the following in the prerealize setup function for the module containing the widget:

PtSetArg( &args[0], Pt_ARG_WEB_SERVER, "online", 0 );
PtSetResources( ABW_web_pane, 1, args );

To use the default off-line web server profile, do the following in the prerealize setup function for the module containing the widget:

PtSetArg( &args[0], Pt_ARG_WEB_SERVER, "offline", 0 );
PtSetResources( ABW_web_pane, 1, args );

Once the server is started, you can check that it was successful by getting the value of Pt_ARG_WEB_STARTUP_ERRNO. For example:

int        *error;

PtSetArg( &args[0], Pt_ARG_WEB_STARTUP_ERRNO, &error, 0 );
PtGetResources( ABW_web_pane, 1, args );

if ( *error != EOK ) {
    /* error occurred - use errno to display message */
}

After successfully starting the server, you can access URLs by setting the Pt_ARG_WEB_GET_URL resources.

Migrating from libPtWeb.so.2 to libPtWeb.so.3

If your browser application has been designed to work with the PtWebClient widget from libPtWeb.so.2, and you want to migrate to the new PtWebClient API in libPtWeb.so.3, you should be aware of some changes that are required in your code:

1. All the macros starting with WWW_ are renamed to start with Pt_WEB_ now. You should change your code accordingly. For example: WWW_RESPONSE_OK is now Pt_WEB_RESPONSE_OK. The compiler will probably make you aware of this if you try to compile code that uses the old macro names.
2. In all the structures that are passed either from the server to PtWebClient or from PtWebClient to the server, members that were char member[] are now pointers to char, char *member.

   This change is particularly important in the structures that are filled in by the user. Therefore the following structures have been renamed to make the compiler aware:

   • PtWebClientAuthenticationData_t — renamed PtWebClient2AuthenticationData_t
   • PtWebClientHelperData_t — renamed PtWebClient2HelperData_t
   • PtWebClientUnknownData_t — renamed PtWebClient2UnknownData_t
   • PtWebClientData_t — renamed PtWebClient2Data_t
   • PtWebCommand_t — renamed PtWebClient2Command_t
   • PtWebClientSSLResponse_t — renamed PtWebClient2SSLResponse_t

   For example, PtWebClientAuthenticationData_t used to be defined as:

   typedef struct {
     short response;
     short type;
     char  userid[255];
     char  password[255];
     char  url[MAX_URL_LENGTH];
   } PtWebClientAuthenticationData_t;

   It's now defined as:

   typedef struct {
     short response;
     short type;
     char  *userid;
     char  *password;
     char  *url;
   } PtWebClient2AuthenticationData_t;

   You should allocate the userid, password and url members , and it's your responsibility to free them.

New resources:

Pt_ARG_WEB_ACTIVATE_LINK (key mode only)

This resource activates and deactivates the current link.

• If the current link is an image map and it's activated, a cursor appears at the top-left corner of the image and the Pt_ARG_WEB_NAVIGATE_LINK resource moves the cursor in the appropriate direction. If you then set Pt_ARG_WEB_ACTIVATE_LINK to 0, the link in the imagemap is activated; if you set this resource to 1, the image map selection is canceled.
• If a form type of TEXTAREA or TEXT is active, setting this resource to 0 gives focus, and a value of 1 removes focus.

Pt_ARG_WEB_AUTHENTICATE

Set this resource to give authentication information to the server when the Pt_CB_WEB_AUTHENTICATE callbacks have been invoked. The data structure used is as follows:

typedef struct {
    short    response;
    short    type;
    char    *userid;
    char    *password;
    char    *url;
} PtWebClient2AuthenticationData_t;
    

The members include:

response

The type of response:

• Pt_WEB_RESPONSE_OK — the information is valid.
• Pt_WEB_RESPONSE_CANCEL — cancel the authentication request.

type

The type of authentication:

• Pt_WEB_BASIC_AUTHENTICATION
• Pt_WEB_DIGEST_AUTHENTICATION
• Pt_WEB_PROXY_AUTHENTICATION.

userid

A pointer to the user's login string.

password

A pointer to the user's password string.

url

A pointer to the URL of the request that invoked the callback.

Pt_ARG_WEB_BUILD_DATE (read only)

The build date of the connected web server.

Pt_ARG_WEB_COMMAND (write only)

Tell the server to perform a specific command. The command is specified in the len argument to PtSetArg(). If a pointer to the PtWebClient2Command_t data structure is required with the command, pass it as the value argument to PtSetArg().

The PtWebClient2Command_t data structure is as follows:

typedef struct {
    union {
        struct {
            char   *filename;
        } SaveasInfo;
        struct {
            char *String;
            unsigned long flags;
        } FindInfo;
        struct {
            char *string;
            int number;
        } SetWidgetInfo;
        struct {
            int input_group;
        } ClipboardInfo;
        char   *scroll_to;
        int     reset_type;
        int     num_purge;
    };
} PtWebClient2Command_t;

The commands are:

Pt_WEB_COMMAND_FIND

Find and highlight a word in the current document. The part of the PtWebClient2Command_t data structure used is:

struct {
    char *string;
    unsigned long flags;
} FindInfo;

where:

• string — a pointer to the word to find in the document.
• flags — a combination of:
  • Pt_WEB_FIND_START_AT_TOP — start the search at the top of the document.
  • Pt_WEB_FIND_MATCH_CASE — match the character case in the word.
  • Pt_WEB_FIND_GO_BACKWARDS — search backward.
  • Pt_WEB_FIND_MATCH_WHOLE_WORDS — match whole words.

Pt_WEB_COMMAND_LOADMISSING

Load any missing images.

Pt_WEB_COMMAND_SAVEAS

Save the current document to disk. The part of the PtWebClient2Command_t data structure used is:

struct {
    char   *filename;
} SaveasInfo;

where filename is a pointer to the name of the file in which to save the document.

Pt_WEB_COMMAND_RESET_OPT

Cause any changed options that may change the current visible page to take effect.

Pt_WEB_COMMAND_PURGE_CACHE

Purge the in-memory image and page cache.

Pt_WEB_COMMAND_LOADMISSING_CONTEXT

Load a missing image whose context is valid (the context is valid after a Pt_CB_WEB_CONTEXT callback).

Pt_WEB_COMMAND_SET_WIDGET

Set the value of a text control. The part of the PtWebClient2Command_t data structure used is:

struct {
        char *string;
        int number;
} SetWidgetInfo;

where:

• string — a pointer to the string that you want to set the contents of the control to.
• number — the numeric ordinal of the control you want to change (as returned in the Pt_CB_WEB_STATUS callbacks of type Pt_WEB_STATUS_CONTENTS).

Pt_ARG_WEB_DATA (write only)

Voyager server only.

This resource is set in response to a Pt_CB_WEB_DATA_REQ callback. It provides the header and data of the client protocol data stream to the browser.

The data structure used is as follows:

typedef struct {
    int     type;
    char   *url;
    int     length;
    char   *data;
} PtWebClient2Data_t;

The members are:

type

Possible values:

• Pt_WEB_DATA_HEADER — the data is the header of the request.
• Pt_WEB_DATA_BODY — the data is the body of the request.
• Pt_WEB_DATA_CLOSE — this flag closes (aborts) the request.

url

A pointer to the URL of this client data stream.

length

The number of bytes of data (no more than what was asked for in the Pt_CB_WEB_DATA_REQ callback).

data

A pointer to the data.

Here's an example of using the client protocol:

int web_data( PtWidget_t *widget, ApInfo_t *apinfo,
              PtCallbackInfo_t *cbinfo )
{
    PtArg_t                 args[1];
    PtWebClient2Data_t       webdata;
    PtWebDataReqCallback_t  *web_data_req = cbinfo->cbdata;
    const char              *html =
"<html><body bgcolor=\"#ffffff\"><p>\
<center><table border=1 bgcolor=\"#f8f7d9\"><tr>\
<td>This is a simple test of the client protocol</td>\
<td><font size=4>Voyager Client: Version 2.01\
<br>Built on: %s<br><hr>\
<font size=4>Voyager Server: %s<br>Built on: %s\
</font></center></td></tr></table></center>
<p>\
</body></html>\n";
    char                    about[512];
    static int              about_sent;

    /* eliminate 'unreferenced' warnings */
    apinfo = apinfo;

    if ( !strcmp( web_data_req->url, "client:about" ) ) {
        if( cbinfo->reason_subtype == Pt_WEB_DATA_HEADER ) {
            const char *data = "Content-Type: text/html\n";
            webdata.type = Pt_WEB_DATA_HEADER;
            webdata.length = strlen(data);
            strcpy( webdata.url, web_data_req->url );
            PtSetArg( &args[0], Pt_ARG_WEB_DATA, data,
                      &webdata );
            PtSetResources( widget, 1, args );
        } else if( cbinfo->reason_subtype == Pt_WEB_DATA_BODY ) {
            /*
             * Since no content length was given, you need
             * to signal EOF with a zero length data packet
             */
            if ( about_sent ) {
                webdata.type = Pt_WEB_DATA_BODY;
                strcpy( webdata.url, web_data_req->url );
                webdata.length = 0;
                PtSetArg( &args[0], Pt_ARG_WEB_DATA, "",
                          &webdata );
                PtSetResources( widget, 1, args );
                about_sent = 0;
            } else {
                char *version, *build_date;

                PtSetArg( &args[0], Pt_ARG_WEB_VERSION,
                          &version, 0 );
                PtSetArg( &args[1], Pt_ARG_WEB_BUILD_DATE,
                          &build_date, 0 );
                PtGetResources(widget, 2, args );
                sprintf( about, html, __DATE__, version,
                         build_date );
                webdata.type = Pt_WEB_DATA_BODY;
                strcpy( webdata.url, web_data_req->url );
                webdata.length = strlen(about);
                PtSetArg( &args[0], Pt_ARG_WEB_DATA, about,
                          &webdata );
                PtSetResources( widget, 1, args );
                about_sent = 1;
            }
        }
    } else {
        if( cbinfo->reason_subtype == Pt_WEB_DATA_HEADER ) {
             /*
              * If I give a content length then I don't need
              * provide a zero byte data packet
              */
            const char *data =
              "Content-Type: text/plain\nContent-Length: 20\n";
            webdata.type = Pt_WEB_DATA_HEADER;
            webdata.length = strlen(data);
            strcpy( webdata.url, web_data_req->url );
            PtSetArg( &args[0], Pt_ARG_WEB_DATA, data,
                      &webdata );
            PtSetResources( widget, 1, args );
        } else if( cbinfo->reason_subtype == Pt_WEB_DATA_BODY ) {
            const char *data = "Unknown client type\n";
            webdata.type = Pt_WEB_DATA_BODY;
            strcpy( webdata.url, web_data_req->url );
            webdata.length = strlen( data );
            PtSetArg( &args[0], Pt_ARG_WEB_DATA, data,
            &webdata );
            PtSetResources( widget, 1, args );
        }
    }
    return( Pt_CONTINUE );
}

Pt_ARG_WEB_DOWNLOAD (write only)

This resource lets you download a file without having to wait for the Pt_CB_WEB_UNKNOWN callback to provide a file. The value argument of PtSetArg() should contain the URL of the file to download and the len argument should contain the filename to save it as.

---

Pt_ARG_WEB_DOWNLOAD does GET requests only.

---

Pt_ARG_WEB_ENCODING

The current document encoding. See PxTranslateSet() in the Photon Library Reference.

For the netfront server, you can set this resource to Autodetect Encoding (the default setting). When this value is set, the netfront server will try to auto detect the encoding.

Pt_ARG_WEB_GET_CERTIFICATES (read only)

This resource gets information about current client certificates.

The data structure used is as follows:

typedef struct {
  int ncert;
  char *url;
  int reserved1;
  int reserved2;
  PtWebSSLCertInfo_t info[1];
  } PtWebSSLClientCertificates_t;

The members are:

ncert

The number of certificates.

url

Not used.

info

A PtWebSSLCertInfo_t structure that contains information about the certificate. See the Pt_CB_WEB_SSL_CERTNONTRUSTED resource for a description of the PtWebSSLCertInfo_t structure.

Pt_ARG_WEB_GET_CONTEXT (read only)

This resource gets the context information, which is valid after a Pt_CB_WEB_CONTEXT callback. To get context information, specify the type in the len argument of PtSetArg().

The possible context types are:

Pt_WEB_CONTEXT_ANCHOR

The URL of a link.

Pt_WEB_CONTEXT_OBJECT

The URL of a image or embedded object.

Pt_WEB_CONTEXT_BKGD

The URL of a background image.

Pt_ARG_WEB_GET_HISTORY (read only)

Use this resource to get the site history list from the browser. This is a list of titles and URLs of all the sites visited in the timeframe specified in the History_Expire option (default 4 days).

The data structures used with this resource are:

typedef struct  {
    short num;
    short offset;
} PtWebClientHistory_t;
    

where:

• num — the number of history entries to return
• offset — the offset into the history site list at which to begin.

and:

typedef struct  {
    char   *title;
    char   *url;
    time_t  lastvisited;

} PtWebClientHistoryData_t;
    

When you use these structures, you pass PtWebClientHistory_t as the value argument to PtSetArg(), and PtWebClientHistory_t as the len argument.

Here's an example of how to get the history:

PtArg_t args[1];
PtWebClientHistoryData_t list[HISTORY_REQUEST_SIZE];
PtWebClientHistory_t list_info;
char *description[HI_MAX_LIST_SIZE];
int i, item_count = 0, loop = TRUE;

list_info.num = HISTORY_REQUEST_SIZE;
list_info.offset = 0;

/* retrieve history list from voyager server */
while (loop) {
    /* get the next 10 history entries */
    PtSetArg(&args[0], Pt_ARG_WEB_GET_HISTORY,
             &list, &list_info);
    PtGetResources( w, 1, args);

    for (i=0; i < 10; i++, item_count++) {
        if (list[i].url[0] == NULL ||
            list[i].url[0] == 0 ||
            item_count >= HI_MAX_LIST_SIZE) {
            loop = FALSE;
            break;
        }
        if ( description[item_count] =
             malloc(strlen(list[i].url) +
                    strlen(list[i].title) + 4) )
            sprintf(description[item_count], "%s\t%s\t",
                    list[i].title, list[i].url);
    }
    list_info.offset += HISTORY_REQUEST_SIZE;
}

Pt_ARG_WEB_GET_URL (write only)

The URL that you want the browser to display or save. Set the len argument of PtSetArg() to one of:

Pt_WEB_ACTION_DISPLAY

Display the URL in the browser.

Pt_WEB_ACTION_SAVEAS

Download and save the URL.

You can OR the following flags into the action to control the caching of the page and the recording of history (these flags are supported by vserver only):

Pt_WEB_NO_MEMORY_CACHE

Don't cache the page in memory.

Pt_WEB_NO_DISK_CACHE

Don't cache the page on disk.

Pt_WEB_NO_SITE_HISTORY

Don't record the site in the site history.

Pt_WEB_NO_PAGE_HISTORY

Don't record the site in the page history.

---

When saving a URL, the browser responds with a Pt_CB_WEB_UNKNOWN to obtain a filename to save the file once it has determined that it can get the URL or see Pt_ARG_WEB_DOWNLOAD . The maximum length of a URL string is 1024 bytes or MAX_URL_LENGTH.

---

Pt_ARG_WEB_HELPER (write only)

Setting this resource tells the server which external helper applications are available. The data structure used is as follows:

typedef struct {
    short   action;
    char    *mimetype;
    char    *suffixes;
    char    *encoding;
    char    *helperapp;
} PtWebClient2HelperData_t;
    

The members of this structure are:

action

The action to take:

• Pt_WEB_ACTION_ADD — add the external helper.
• Pt_WEB_ACTION_DELETE — delete the external helper (if added previously).

mimetype

A pointer to the mimetype of the data that the helper application can handle.

suffixes

A pointer to the file suffixes of the helper application data files (e.g. "mpeg mpg").

encoding

Currently not used.

helperapp

A pointer to the complete filename to the helper application; use %s to indicate where the data file should appear on the command line.

---

If you wish to control the running of the helper application yourself, add the helper with no help application (i.e. helperapp=""). A Pt_CB_WEB_UNKNOWN callback is called if an HTML page contains an <embed> tag to a file with the mimetype or suffix provided. (Normally these files are ignored.)

---

Pt_ARG_WEB_H_ERRNO

The value of h_errno after a DNS failure. The possible values are:

HOST_NOT_FOUND

No such host is known.

NO_DATA

The name is known to the name server, but has no IP address associated with it—this isn't a temporary error. Another type of request to the name server using this domain name results in an answer (e.g. a mail-forwarder may be registered for this domain).

NO_RECOVERY

Some unexpected server failure was encountered. This is a nonrecoverable error.

TRY_AGAIN

This is usually a temporary error and means that the local server didn't receive a response from an authoritative server. A retry at some later time may succeed.

Pt_ARG_WEB_IMPORT_CERTIFICATE

NetFront server only.

Set this resource when you want a client certificate to be imported.

The data structure used is as follows:

typedef struct {
  int type;
  char *path;
  } PtWebImportCertificate_t;
    

The members include:

type

The type of certificate to be imported. It can be one of:

• Pt_WEB_CERT_TYPE_DER — x509 certificate
• Pt_WEB_CERT_TYPE_PKCS7
• Pt_WEB_CERT_TYPE_PKCS12

path

The full path to the file that contains the certificate data.

After you set this resource, the netfront server starts importing the certificate. If the certificate is password-protected, netfront issues a Pt_CB_WEB_AUTHENTICATE with type=Pt_WEB_IMPORT_CERT_AUTHENTICATION. (In this case action, realm, and url aren't used.) The client responds by setting the password member of the Pt_ARG_WEB_AUTHENTICATE resource. The netfront server then continues importing the certificate. If an error or a warning needs to be displayed, the Pt_CB_WEB_SSL_ERROR and Pt_CB_WEB_SSL_CERTNONTRUSTED are invoked with reason set to Pt_WEB_SSL_IMPORT_CERT.

At the end of the import process, a Pt_CB_WEB_IMPORT_CERTIFICATE is invoked indicating whether the process was successful or not.

Pt_ARG_WEB_NAVIGATE_FRAME

Controls focus navigation of FRAMES pages when the browser is in key mode. Set the value argument of PtSetArg() to one of:

Pt_WEB_DIRECTION_UP

Focus the frame above the current one.

Pt_WEB_DIRECTION_DOWN

Focus the frame below the current one.

Pt_WEB_DIRECTION_LEFT

Focus the frame to the left of the current one.

Pt_WEB_DIRECTION_RIGHT

Focus the frame to the right of the current one.

Pt_WEB_DIRECTION_FWD

Focus the next frame.

Pt_WEB_DIRECTION_BACK

Focus the previous frame.

---

The next and previous directions are defined by the order of the <FRAME> tags in each <FRAMESET> tag.

---

Pt_ARG_WEB_NAVIGATE_LINK

This resource controls focus navigation of links on the current page when the browser is in key mode. Set the value argument to PtSetArg() to one of the following:

Pt_WEB_DIRECTION_UP

Focus the link above the current one.

Pt_WEB_DIRECTION_DOWN

Focus the link below the current one.

Pt_WEB_DIRECTION_LEFT

Focus the link to the left of the current one.

Pt_WEB_DIRECTION_RIGHT

Focus the link to the right of the current one.

Pt_WEB_DIRECTION_FWD

Focus the next link.

Pt_WEB_DIRECTION_BACK

Focus the previous link.

Pt_WEB_DIRECTION_FIRST

Focus the first link on the current page.

Pt_WEB_DIRECTION_LAST

Focus the last link on the current page.

When an IMAGE-MAP type link has been activated, this resource is used to navigate the “ImageMap_Cursor” over the image map in the specified direction. The len argument is then used to specify the number of pixels to move the cursor.

When a FORM type object has been activated (given focus), these commands are turned into cursor-key directions and given to the form object.

---

The next and previous directions are defined by the order of the links in the HTML page.

---

Pt_ARG_WEB_NAVIGATE_PAGE

This resource controls the scrolling of the displayed page and the ability to navigate back and forward through pages in the page history. Set the value argument to a direction and the len argument to the amount to scroll, in percentage of the visible page (e.g. 100 to scroll one full page). The direction must be one of:

Pt_WEB_DIRECTION_UP

Scroll the page up.

Pt_WEB_DIRECTION_DOWN

Scroll the page down.

Pt_WEB_DIRECTION_LEFT

Scroll the page to the left.

Pt_WEB_DIRECTION_RIGHT

Scroll the page to the right.

Pt_WEB_DIRECTION_FWD

Go to the previous page in the page history.

Pt_WEB_DIRECTION_BACK

Go to the next page in the page history.

---

The len argument has no effect when using Pt_WEB_DIRECTION_FWD or Pt_WEB_DIRECTION_BACK.

---

Getting the value of this resource indicates whether or not you can perform a given operation. Currently, only Pt_WEB_DIRECTION_FWD and Pt_WEB_DIRECTION_BACK are supported.

The format of the data returned is 1 << Pt_WEB_DIRECTION_xx. For example:

int    *nav_dir;

PtSetArg( &arg, Pt_ARG_WEB_NAVIGATE_PAGE, &nav_dir, 0 );
PtGetResources( webclient, 1, args );

if ( *nav_dir & (1 << Pt_WEB_DIRECTION_FWD ) ) {

    /* I can go forward in the page history  */

} else if ( *nav_dir & (1 << Pt_WEB_DIRECTION_BACK ) ) {

    /* I can go backward in the page history */

}

Pt_ARG_WEB_OPTION

Set this resource to set options on the web server. This resource takes two parameters:

• value — the setting of the options.
• len — the string that describes the option.

For example, to change the scrollbar size:

PtArg_t args[1];

PtSetArg( &args[0], Pt_ARG_WEB_OPTION, "10",
          "iScrollbarSize" );
PtSetResources( webclient_wgt, 1, args );
    

You can read the options from the server by getting the value of this resource. The following piece of code increases the font size by one level:

char *size;

PtSetArg( &args[0], Pt_ARG_WEB_OPTION, &size,
          "iUserTextSize" );
PtGetResources( ABW_web_pane, 1, args );

if ( size ) {
    fontsize = atoi( size );
    if ( fontsize < 3 ) {
        sprintf( buf, "%d", fontsize + 1 );
        PtSetArg( &args[0], Pt_ARG_WEB_OPTION,
                  buf, "iUserTextSize" );
        PtSetResources( ABW_web_pane, 1, args );
    }
}

---

If you're changing options that have visual effects after the PtWebClient widget is realized, then you must issue a reset command in order for the changes to be seen. The command is as follows: PtSetArg( &args[0], Pt_ARG_WEB_COMMAND, 0, Pt_WEB_COMMAND_RESET_OPT ); PtSetResources( ABW_web_pane, 1, args );

---

The following sections list the options and their defaults:

• HTML Options
• HTTP cookie options
• Authentication options
• FTP options
• Gopher options
• HTTP options
• File options
• Image options
• Print options
• SOCKS options
• TCP/IP options
• Disk Cache options
• Miscellaneous options
• NetFront-specific options

HTML Options

The HTML options are:

A:active color

The color of a link when you click on it with the mouse.

Default: "#ff0000"

A:link color

The normal color of a link.

Default: "#0000ff"

A:visited color

The color of a link after it's been visited.

Default: "#008080"

bAutoLoadImages

Voyager server only.

If "TRUE", images are loaded as they're encountered in the page. If "FALSE", images are loaded only if the Pt_WEB_COMMAND_LOADMISSING command is issued.

Default: "TRUE"

bDisableHighlight

Voyager server only.

Don't highlight text while dragging over it.

Default: "FALSE"

bDisableImagePlaceHolders

Voyager server only.

Disable drawing image placeholders for missing or invalid images.

Default: "FALSE"

bIgnoreDocumentAttributes

Voyager server only.

If "TRUE", color attributes override what's specified in the page.

Default: "FALSE"

bkey_mode

Voyager server only.

If set to "TRUE", key navigation is enabled.

Default: "FALSE"

BODY background

The color of the page background.

Default: "#ffffff"

BODY color

The color of text inside the body on the HTML page.

Default: "#000000"

BODY font-family

The font family name of the text in the body portion of the page.

BODY margin-right

The margin, in pixels, between right side of display area and the first visible element in the page (Note: page tags may override this).

Default: "10"

BODY margin-top

The margin, in pixels, between top of display area and the first visible element in the page (Note: page tags may override this).

Default: "20"

bot_border_color

Voyager server only.

The bottom color of borders in frame pages.

Default: "#606060"

bot_focus_color

Voyager server only.

The bottom color of the focus box in key mode.

Default: "#7f7f00"

bUnderlineLinks

If "TRUE", the link on a page is underlined.

Default: "TRUE"

bview_source

Voyager server only.

Allow page source to be viewed. Setting this option to "FALSE" saves memory.

Default: "TRUE"

disable_exception_dlg

Don't allow the Javascript exception dialog to be displayed.

Default: "FALSE"

disable_new_windows

Don't allow Javascript windows to open.

Default: "FALSE"

enable_link_arm

Voyager server only.

Activate links on arming (useful for touch screens).

Default: "FALSE"

enable_print_bgcolor

Voyager server only.

Print background colors.

Default: "FALSE"

Focus_Outline_Color

NetFront only

The colour of the focus outline, in RGB format.

Default: "#9098F8"

form_font

Voyager server only.

The font used for lists, comboboxes, submit buttons and reset buttons.

frame_spacing

Voyager server only.

The spacing between frames, in pixels.

Default: "2"

H* font-family

Voyager server only.

The font family name of the text used in headings on the page.

iReformatHandling

Voyager server only.

Reformat handling

Default: "2"

Possible values:

• "0" — no progressive formatting or display. Subviews can be progressively requested, but nothing formats or displays until the document reaches a totally stable state. This mode is commonly used for kiosk browsers and is also useful for devices.
• "1" — reformat once after all subviews are loaded. Text is displayed immediately as it comes in, and subviews that have size hints are displayed as they arrive without reformatting. Reformatting isn't done until the entire document is complete. However, any other reformatting, such as resizing the window, brings those subviews with size hints onto the screen.
• "2" — reformat the GUI after each subview is loaded. Any subviews with size hints are displayed without reformatting. However, subviews without hints trigger a partial reformat as soon as their size is known, so they can be displayed immediately.

iScrollbarSize

The scrollbar width, in pixels.

Default: "16"

iUserTextSize

The base logical font size of text size used in the page.

Defaults:
Voyager — "2"
NetFront — "100"

Possible values:
Voyager uses values between "0" and "4" for small to large text, with "2" being average size.
NetFront uses values larger than "5", which represent the percent of original size of the text, with "100" being the original size.

java_disable

Voyager server only.

Disable Java applet tag parsing (forced "TRUE" if vgr_javanpl.so isn't found).

Default: "FALSE"

mono_form_font

Voyager server only.

The font used for editable form fields.

PRE font-family

Voyager server only.

The font family name used for preformatted text ( this should be a fixed-width font).

top_border_color

Voyager server only.

The top color of borders in frame pages.

Default: "#ffffff"

top_focus_color

Voyager server only.

The top color of the focus box in key mode.

Default: "#ffff00"

underline_width

Voyager server only.

The line thickness, in pixels, of the underline used on links.

Default: "1"

HTTP cookie options

The HTTP cookie options are:

cookiejar_name

The name of file to store cookie information in.

Default: "cookie.jar"

cookiejar_path

The directory used to write the cookie file in.

Default: "$(HOME)"

cookiejar_save_always

Voyager server only.

Always keep the cookie-jar file on disk up-to-date.

Default: "FALSE"

cookiejar_size

The maximum size, in bytes, that the cookie-jar file is allowed to grow. A value of "-1" means no limit.

Default: "-1"

Authentication options

The authentication options are:

max_password_guesses

Voyager server only.

The maximum number of guesses allowed when performing authentication.

Default: "3"

FTP options

The FTP options are:

email_address

Voyager server only.

The email address used for the password on anonymous logins on the FTP server.

Default: "80"

ftp_proxy_host

Voyager server only.

The host name or IP address of proxy server for FTP requests.

Default: none

ftp_proxy_port

Voyager server only.

The port number on the FTP proxy server to use.

Default: "80"

proxy_overrides

A comma-separated list of host names or IP addresses to bypass the FTP proxy server when accessed.

Default: "80"

Gopher options

The Gopher options are:

gopher_proxy_host

Voyager server only.

The host name or IP address of the proxy server for gopher requests.

Default: none

gopher_proxy_port

Voyager server only.

The port number on the gopher proxy server to use.

Default: "80"

proxy_overrides

A comma-separated list of host names or IP addresses to bypass the gopher proxy server when accessed.

Default: none

HTTP options

The HTTP options are:

http_proxy_host

The host name or IP address of the proxy server for HTTP requests.

Default: none

http_proxy_port

The port number on the HTTP proxy server to use.

Default: "80"

proxy_overrides

A comma-separated list of host names or IP addresses to bypass the HTTP proxy server when accessed.

Default: none

File options

The file options are:

file_display_dir

Voyager server only.

Display directory listings as HTML pages. For example, file:/ produces an HTML page with the content of the root directory.

Default: "TRUE"

file_strict_access

Voyager server only.

Enable strict file access (file: URLs must have the Pt_WEB_STRICT_FILE_ACCESS flag set when requested via Pt_ARG_WEB_GET_URL or Pt_ARG_WEB_DOWNLOAD).

Default: "FALSE"

Image options

The image options are:

bProgressiveImageDisplay

Display images progressively as they're being loaded.

Default: "TRUE"

concurrent_decodes

The number of concurrent JPEG decodings that should be done. This option is write-only. This option can save significant memory when decoding JPEGS to 256 colors.

Default: "4"

quantize_jpegs

Voyager server only.

Always convert JPEGs to a 256-color palette. (The default is based on the current graphics mode; if running on a high-color or direct-color graphics driver, JPEGs are converted to the default color mode, usually 24-bit. If a palette-based graphics driver is running, the JPEGs are always converted to 256 colors using the current hardware palette, and setting this option has no effect.)

Default: "FALSE"

Print options

The print options are:

Print_Left_Footer_String

The left footer used when printing.

Default: "Page &"

Print_Left_Header_String

The left header string used when printing.

Default: "&w"

Print_Header_Font

The font used in the header and footer.

Default: "helv"

Print_Header_Font_Size

The font size used in the header and footer.

Default: "8"

Print_Right_Footer_String

The right footer used when printing.

Default: "&d &t"

Print_Right_Header_String

The right header string used when printing.

Default: "&u"

You can use these special characters in the header and footer strings:

"&w"

Page title.

"&u"

URL.

"&p"

Page number.

"&d"

Date — American style (“mmm dd yyyy”).

"&D"

Date — European style (“dd mmm yyyy”).

"&t"

Time — 12-hour format (“HH:MM am”).

"&T"

Time — 24-hour format (“HH:MM”).

"&&"

The ampersand ("&") character.

SOCKS options

These options are for the Voyager server only. The SOCKS options are:

socks_app

The application name to pass to the SOCKS server.

Default: none

socks_port

The port number on the SOCKS server to use.

Default: none

socks_server

The host name or IP address of the SOCKS server for any requests.

Default: none

socks_user

The user ID to pass to the SOCKS server.

Default: none

TCP/IP options

The TCP/IP options are:

file_buckets

Voyager server only.

Fill network buffers before processing them.

Default: "TRUE"

max_connections

Default: "4"

socket_timeout

Voyager server only.

Default: "2400"

Disk-cache options

The disk-cache options are:

clear_main_cache_on_exit

Clear the on-disk cache when the browser exits.

Default: "FALSE"

dcache_verify_policy

0 means never verify if the document has changed;
1 means verify if the document has changed once per session;
2 means always verify if the document has changed.

Default: "0"

Note: Verifying is done by using the “If-Modified-Since” request-header.

enable_disk_cache

Enable on-disk caching.

Default: "TRUE"

keep_index_file_updated

Voyager server only.

Keep the disk-cache index file updated on disk when it changes, instead of updating it once on exiting.

Default: "FALSE"

main_cache_dir

Voyager server only.

The directory used to store cache files.

Default: "/tmp"

main_cache_kb_size

The maximum size of the on-disk cache.

Default: "5000"

main_index_file

Voyager server only.

The name of the cache index file.

Default: "main.ndx"

Miscellaneous options

The miscellaneous options are:

IBeam_Cursor

See /usr/include/photon/PhCursor.h

Default: "e90e" (the insert cursor)

Link_Cursor

See /usr/include/photon/PhCursor.h

Default: "e90c" (the finger cursor)

Normal_Cursor

See /usr/include/photon/PhCursor.h

Default: "e900" (the pointer cursor)

Page_History_Length

The maximum number of pages allowed in the page history (back/forward history).

Default: "50"

Use_Anti_Alias

Use anti-aliased fonts.

Default: "TRUE"

Use_Double_Buffer

Enable double-buffered rendering.

Default: "TRUE"

Visitation_Horizon

The number of days after which to expire the visited links display (i.e. VLINK -> LINK).

Default: "4"

Voyager-server-only miscellaneous options:

Accept_Charset_Header

The value string to pass with the Accept-Charset header (see the HTTP specification).

Default: "TRUE"

Accept_Language_Header

The value string to pass with the Accept-Language header (see the HTTP specification).

Default: "TRUE"

Global_History_File

The full pathname of the file to store the site history list in. (Note: this page is an HTML-formatted page.)

Default: none

History_Expire

The number of days used to expire entries in the site history list. (Note: set to "0" to remove the history when the client is shut down and restarted.)

Default: "4"

Image_Cache_Size_KB

The size of image cache, in kilobytes.

Default: "1024"

ImageMap_Cursor

See /usr/include/photon/PhCursor.h

Default: "e90c" (the finger cursor)

ImageMap_Cursor_NoLink

See /usr/include/photon/PhCursor.h

Default: "e900" (the pointer cursor)

LinkWait_Cursor

See /usr/include/photon/PhCursor.h

Default: "e918" (the point-wait cursor)

NormalWait_Cursor

See /usr/include/photon/PhCursor.h

Default: "e918" (the point-wait cursor)

Page_Cache_Size

The number of pages kept in memory.

Default: "4"

Safe_Memory_Free

The minimum amount of memory, in kilobytes, to leave for the system. If the system has less than this amount available, Voyager's requests to allocate memory fail.

Default: "0"

Show_Server_Errors

Display the HTML-formatted error pages received from the remote HTTP servers. Otherwise, generate a Pt_CB_WEB_ERROR callback.

Default: "FALSE"

Site_History_Length

The maximum number of sites allowed in the site history (the list is obtained from server).

Default: "500"

Use_Explicit_Accept_Headers

Send an explicit Accept: content-type header request field in the HTTP header; otherwise send Accept: */*.

Default: "TRUE"

Wait_Cursor

See /usr/include/photon/PhCursor.h

Default: "e908" (the wait cursor)

NetFront-specific options

These options are specific to the netfront server.

ServerId

(Read only) The string identifier for the server. You can use this string if your client can be used with both the vserver and netfront servers, and you want to do specific things when connected to a certain server. The strings returned are vserver and Netfront, respectively.

iUserZoom

A numeric value for the global (text and image) zoom factor, in percent. A value of "100" means original size.

fNavigatorUserAgent

The user agent string.

memory_cache_kb_size

The amount of in-cache memory. The default is 0.

fEnableWML

Enable Wireless Markup Language (WML/WAP) support. The default is "FALSE".

fDisableSelection

Disable text slection. When "TRUE", a user can't select HTML text in the netfront canvas. The default is "FALSE".

fDisableJavascriptAlert

Disable Javascript alert() dialogs. When "TRUE", JavaScript alert() dialogs aren't displayed. The default is "FALSE".

fDisableJavascriptConfirm

Disable Javascript confirm() dialogs. When "TRUE", JavaScript confirm() dialogs aren't displayed. The default is "FALSE".

fDisableJavascriptPrompt

Disable Javascript prompt() dialogs. When "TRUE", JavaScript prompt() dialogs aren't displayed. The default is "FALSE".

These options are write-only:

fRunJavaScript

If "TRUE", JavaScript is enabled.

Default: "TRUE"

fScriptDisables

Validates/invalidates external script files. Possible values are:

• "DISABLE_SCRIPT_SRC" — invalidates the src attribute of the <script> element. The external script isn't read.
• "DISABLE_SCRIPT_EXECUTE" — invalidates scripts in newly generated Windows.
• "DISABLES_NONE" — no disabling.

Default: "DISABLES_NONE"

fCSSDisables

Options used to configure CSS. Possible values are:

• "DISABLE_CSS_DEFAULT" — default style sheet is invalid.
• "DISABLE_CSS_LINK" — external file definition (LINK REL) style sheet is invalid.
• "DISABLE_CSS_IMPORT" — import (@import) style sheet is invalid.
• "DISABLE_CSS_STYLETAG" — <style> tag is invalid.
• "DISABLE_CSS_STYLEATTR" — style attribute is invalid.

Set to "FLAG_NONE" to clear all flags.

Default: all flags enabled.

fSSLVersion

The version of SSL to use. Can be a combination of values:

• "V2" — use SSL version 2.
• "V3" — use SSL version 3.
• "TLS" — use TLS version 1.

Set to "FLAG_NONE" for none.

Default: all flags enabled.

fDisplayTable

Sets whether the browser displays <table> elements described in content by table style or not.

Default: "TRUE"

fDisplayImage

Sets whether the browser displays images.

Default: "TRUE"

fAnimateImage

Sets whether the browser animates images.

Default: "TRUE"

fWaitDecodeImage

Sets whether the browser waits until an image is displayed to decode it.

Default: "FALSE"

fAnimationImageMaxLoops

The maximum number of animation loops for images. No limit if set to "-1".

Default: "-1"

fMaxImageDelayTime

The maximum delay time for animations, in milliseconds. No limit if less than "0".

Default: "-1"

fMinImageDelayTime

The minimum delay time for animations, in milliseconds. No limit if less than "0".

Default: "-1"

fMaxImageWidth

The maximum display width size of images, in pixels. Possible values are:

• greater than "0" — if the width of the image is larger than this, the image is scaled so its width equals fMaxImageWidth.
• equal to "0" — the image is displayed at its real size.
• less than "0" — specifies the negative of the maximum size of a viewport. If the width of an image is larger than that of the viewport, it is resized to the width of the viewport. If the image size to be displayed is larger than the specified value, the reduction decode is attempted. If the reduction decode is impossible, the image is resized again when it is displayed.

Default: "0"

fMaxImageHeight similar

The maximum display height size of image (in pixels). Possible values are:

• greater than "0" — if the height of the image is larger than this, the image is scaled so its height equals fMaxImageHeight.
• equal to "0" — the image is displayed at its real size.
• less than "0" — specifies the negative of the maximum size of a viewport. If the height of an image is larger than that of the viewport, it is resized to the height of the viewport. If the image size to be displayed is larger than the specified value, the reduction decode is attempted. If the reduction decode is impossible, the image is resized again when it is displayed.

Default: "0"

fMaxPixelsPerImage

The maximum image size, which is the width × height, in pixels. No limit if set to "-1".

This sets the maximum image file size that can be displayed. The size is determined by the width and height recorded in the image file before the browser engine converts the size. It isn't related to the attribute values specified by the image's HTML tag. If the image size is larger than the specified value or the image header is damaged, the browser cancels decoding and it displays the image-data-damaged icon. This prevents a memory shortage when the browser attempts to reserve memory for an abnormally large image.

Default: "-1"

fKeepResizedImage

Sets whether the browser retains a temporary image or not when it scales an image up or down.

Default: "FALSE"

fMaxPixelsPerDecodedPixelMap

Sets the maximum pixel map size. Possible values are:

• > "0" — the maximum pixel map size when decoding an image, in pixels.
• "-1" — no limitation on the pixel map size.

Default: "-1"

If a large image causes a lack of memory when it's decoded, nothing can be displayed. Setting the appropriate value for fMaxPixelsPerDecodedPixelMap enlarges the reduced image again, and enables the browser to display the rough image with a resolution lower than its original.

If the pixel map size is larger than the specified maximum size, a reduction decode is attempted so that the image is the specified size or smaller. If the decoder is unable to reduce the image to the specified size, the image-data-damaged icon is displayed.

fDeleteImageBound

Possible values are:

• "INT_MIN" — release all the pixelmaps that have been already decoded.
• "-1" — keep all the pixelmaps that have been already decoded.
• ≥ "0" — the margin outside the visible display area where pixelmaps are not released. The pixelmaps in the range of the visible display area plus the specified margin (in pixels) are not released, and the browser decodes images that haven't been decoded yet. Pixelmaps outside the visible display area are released.
• "INT_MAX" — decode all the images that haven't been decoded yet. Pixelmaps aren't released.

Default: "-1"

fImageResizeAlgorithm

The algorithm to use to reduce images. Possible values are:

• "IMAGERESIZE_SIMPLE"
• "IMAGERESIZE_BILINEAR"

Default: "IMAGERESIZE_SIMPLE"

fPixelMapProtectInMemoryCrisis

Sets whether to protect (by releasing) the pixelmap or not when a memory error occurs, except when processing images.

Default: "TRUE"

fMaxActiveDecoders

The maximum number of image decoders that can operate at the same time (except the image decoder operating on animation). No limit when set to -1.

Default: "-1"

fIncrementalReflow

Possible values are:

• "TRUE" — Execute incremental reflow. The browser displays elements one by one, even if the layout information isn't calculated. It lays out again if the element is changed when the layout information is decided.
• "FALSE" — Don't execute incremental reflow.

Default: "FALSE"

fTextareaRows

Default value for the rows attribute of the <textarea> element.

Default: "4"

fTextareaCols

Default value for the cols attribute of the <textarea> element.

Default: "20"

fBlinkOnPeriod

The “on” time for the <blink> element, in milliseconds.

Default: "1500"

fBlinkOffPeriod

The “off” time for the <blink> element, in milliseconds.

Default: "800"

fBlinkLimitTime

The time limit for blinking of the <blink> element, in milliseconds. Set to "-1" for no limit.

Default: "-1"

fWapMarqueeSpeedFast

The fast speed of a <marquee> element, in milliseconds.

Default: "60"

fWapMarqueeSpeedNormal

The normal speed of a <marquee> element, in milliseconds.

Default: "82"

fWapMarqueeSpeedSlow

The slow speed of a <marquee> element, in milliseconds.

Default: "100"

fWaitStartMarquee

Specifies whether to delay scrolling a <marquee> element until the marquee is displayed.

Default: "FALSE"

fMaxTotalContentsSize

The maximum size, in bytes, of the content displayed in one page. This setting requires a restart to take effect. Set it to "-1" for no limit.

Default: "-1"

Fit_Into_Pane

Turns Smart-Fit mode on or off. Smart-Fit fits a display to the window width.

Default: "FALSE"

fProgressiveOnlyDisplayed

Sets how progressive display works:

• "TRUE" — The browser formats the visible content progressively, and then formats the rest of the content. This shortens the time required to display a page.
• "FALSE" — Formats all content progressively.

Default: "TRUE"

fDisplayCompact

Sets the behavior if content protrudes off the screen:

• "TRUE" — Ignore all margin and padding settings.
• "FALSE" — Don't ignore margin and padding.

Default: "FALSE"

fTabWidth

Sets the width of the tab character in the <pre> element.

Default: "8"

fEnableFrameSet

Enables the <frameset> tag.

Default: "TRUE"

fEnableIFrame

Enables the <iframe> tag.

Default: "TRUE"

fInhibitLineOverlap

Prevents lines of text from overlapping in the situation where a small value is set for line-height in a style sheet, but there's no small font.

Default: "FALSE"

fCanvasMarginWidth

The margin width of the drawing content area. This is the default value of the <body> tag.

Default: "2"

fCanvasMarginHeight

The margin height of the drawing content area. This is the default value of the <body> tag.

Default: "2"

fRememberFormValue

Sets whether the browser saves the content entered in a form to its history (excluding <input> where "type" is password).

Default: "TRUE"

fEnableClientPull

Allows the browser to attempt a connection due to a client pull when it is browsing off-line.

Default: "TRUE"

fNotifyInclError

Indicates whether the browser notifies you if an error occurs when loading embedded content, such as images.

Default: "FALSE"

fPDConfig

Specifies when mouse events are generated. Can be one of these values:

• "NO_MOUSE_MOVE" — generate mouse over at the time of mouse down, and generate mouse out at the time of mouse up.
• "NO_POINTING_DEVICE" — generate mouse over at the time of on focus, and generate mouse out at the time of on blur.

Or: "FLAG_NONE" — none of the above.

Default: "FLAG_NONE"

fAutoSetFocus

Specifies whether focus is set if there is a focus target on screen:

• "TRUE" — set a focus automatically.
• "FALSE" — don't set focus automatically.

Default: "FALSE"

fAccesskeyFocusOnlySubmitReset

Specifies the behavior of pressing the access key specified by the accesskey attribute of form <input> elements:

• "TRUE" — don't execute a send/reset when the access key is pressed, but only move the focus.
• "FALSE" — execute a send/reset when the access key is pressed.

Default: "FALSE"

fEnableTabIndex

Specifies whether a tab index is enabled:

• "TRUE" — tab index is valid.
• "FALSE" — tab index is invalid.

Default: "TRUE"

fTabOrder

Specifies the tab order:

• "TABORDER_DOCTREE" — tab order is determined by the description in the document, set by the tabindex attribute.
• "TABORDER_DISPLAY" — tab order starts from the y coordinate of the upper edge of the focusable elements in the focus area.
• "TABORDER_BASELINE" — tab order starts from the y coordinate of the lower edge of the focusable elements in the focus area.

Default: "TABORDER_DISPLAY"

fFocusOutlineWidth

Specifies the border for image maps or buttons with focus, in pixels. Must be ≥1.

Default: "1"

fFocusOutlineWidthForControl

Specifies the border for controls with focus, in pixels:

• ≥"0" — the border width of the focus frame.
• "-1" — don't draw the focus frame, even though the focus was retrieved.

Default: "1"

fFocusOutlineWidthForIFrame

The border width of the focus frame, in pixels, for the inline frame.

Default: "1"

fContentParserMaxStayTime

The maximum time for the “content parser progress”, before it can be interrupted, in milliseconds. This process analyzes the text data and builds the internal DOM tree. Set to "0" or more.

Default: "100"

---

Higher values for “progress stay” times can result in faster page-rendering times. Lower values means the process is interrupted more often, possibly resulting in slower rendering times, but also allowing processes other than the browser engine more processor time.

---

fPageMakerMaxStayTime

The maximum time for the “page maker progress”, before it can be interrupted, in milliseconds. Set to "0" or more.

Default: "100"

---

Higher values for “progress stay” times can result in faster page rendering times. Lower values means the process is interrupted more often, possibly resulting in slower rendering times, but also allowing processes other than the browser engine more processor time.

---

fEditorMaxStayTimeFG

The maximum time for the “editor progress” for the visible display area, in milliseconds. In this process, the rendering engine calculates the layout information and draws the content to the currently displayed area. Set to "0" or more.

Default: "100"

---

Higher values for “progress stay” times can result in faster page rendering times. Lower values means the process is interrupted more often, possibly resulting in slower rendering times, but also allowing processes other than the browser engine more processor time.

---

fEditorMaxStayTimeBG

The maximum time for the “editor progress” for the undisplayed area, in milliseconds. In this process, the rendering engine calculates the layout information for the area that isn't currently displayed. Set to "0" or more.

Default: "100"

---

Higher values for “progress stay” times can result in faster page rendering times. Lower values means the process is interrupted more often, possibly resulting in slower rendering times, but also allowing processes other than the browser engine more processor time.

---

fUseHTTP11PipeLine

Sets whether the browser uses pipelining in HTTP/1.1.

Default: "FALSE"

fCookieMode

Cookie processing mode:

• "COOKIE_NOTIFY_BEFORE_SET" — notify before setting a cookie.
• "COOKIE_ALWAYS_SET" — always set.
• "COOKIE_NEVER_SET" — never set.

Default: "COOKIE_NOTIFY_BEFORE_SET"

fMaxStreams

Maximum number of simultaneous TCP connections.

Default: "4"

fMaxRequestHeader

The maximum HTTP request line size, in bytes.

Default: "-1" (no limit)

fMaxRequestBody

The maximum HTTP request body size, in bytes.

Default: "-1" (no limit)

fMaxTotalCookies

The maximum number of cookies.

Default: "300"

fMaxCookiesPerDomain

The maximum number of cookies for each domain.

Default: "20"

fMaxLenPerCookie

The maximum size per cookie, in bytes.

Default: "4096"

fMaxRedirect

The maximum number of redirects.

Default: "30"

fMaxPageAuth

The maximum number of authentications per page.

Default: "-1" (no limit)

fMaxProxyAuth

The maximum time for authentication per proxy.

Default: "-1" (no limit)

fSendProxyKeepAlive

Transmit Proxy-Connection: KeepAlive header at HTTP.

Default: "TRUE"

fSendReferer

Transmit Referer header at HTTP.

Default: "TRUE"

fSendCookie

Transmit cookies.

Default: "TRUE"

fDisableFilep

Disable file protocol.

Default: "FALSE"

fAllowHTTPandHTTPS

Display HTTPS content in HTTP content, or display HTTP content in HTTPS content.

Default: "TRUE"

fBlockquoteMargin_left

The left margin when drawing a <blockquote> element, in pixels.

Default: "30"

fBlockquoteMargin_right

The right margin when drawing a <blockquote> element, in pixels.

Default: "30"

fBlockquoteMargin_top

The top margin when drawing a <blockquote> element, in pixels.

Default: "19"

fBlockquoteMargin_bottom

The bottom margin when drawing a <blockquote> element, in pixels.

Default: "19"

Pt_ARG_WEB_PRINT (write-only)

Set this resource to print the page. You can use the len argument of PtSetArg() to specify a combination of the following flags:

Pt_WEB_PRINT_FROM_CACHE

When printing, let the print filters read images from the image cache, to reduce the size of intermediate file.

---

Use this option only if the filter is run locally. It's up to the client application to prevent any activation in the server while printing.

---

Pt_WEB_PRINT_ALL_FRAMES

Print all frames as shown on the current page.

Pt_ARG_WEB_RELOAD (write only)

This is a write-only resource without any specified type. Set it to any value to reload the current page:

PtSetArg (&args[0], Pt_ARG_WEB_RELOAD, 0, 0);
PtSetResources (widget, 1, args);

Pt_ARG_WEB_SERVER

The name of a web-server profile to use, or the path and any options to the web server to start. Setting this resource starts the server; if there's a server already attached to the client, it's shut down and the new one is started.

Web-server profiles are stored in $HOME/.ph/webservers (the user profile) and /etc/photon/webservers (the global profile). The user profile is searched first. The format of this file is:

profile= server,name

In this format, server is the server executable, including path and command-line options if required, and name is the named connection that the client must use to establish a connection to the server. Profile names aren't rigidly defined, so you can use any name that suits your application if you create a custom profile. The file can contain whitespace, and lines that start with # are comments. If you need to use a comma in a command-line option, use quotation marks around the command line.

Here's an example:

# default server for "online" browsing (i.e. www)
online = vserver,VoyagerServer-2

#default server for "offline" browsing (i.e. files on disk)
offline = vserver.file -l -nVoyagerOffline,VoyagerOffline

# server profile for using Mozilla engine
mozilla = mozilla -sshared,MozillaServer

# my own webserver - an example of using ','
myserver = "/foo/bar/mywebserver -oOpt1,Opt2",MyServer

If no matching profile is found, then the string is taken literally as the server to spawn, and the setting for Pt_ARG_CLIENT_NAME is used to connect to the spawned server.

---

You can bypass the profile lookup by beginning the Pt_ARG_WEB_SERVER string with the @ character. PtWebClient discards the @ and uses the remainder as the command to start the web server. In this scenario, the setting for Pt_ARG_CLIENT_NAME is used to connect to the server.

---

You can use web-server profiles to override the web server used by existing applications. For example, if an application tries to start the vserver server, you can cause it to use mozilla instead with the following profile:

# default server for old Voyager client
vserver = mozilla -sshared,MozillaServer

---

Any options set prior to setting the resource are set back to their defaults.

---

For an example of using this resource, see “Starting the server,” above.

Pt_ARG_WEB_SERVER_PID (read only)

A read-only resource that returns the PID of the web server. The value is 0 if the widget has connected to an existing server, or -1 if spawn() has failed.

Pt_ARG_WEB_SSL_RESPONSE

A resource that's used only if you're using the SSL (Secure Sockets Layer) version on the web server. This resource is used in response to the Pt_CB_WEB_SSL_CERTNONTRUSTED and Pt_CB_WEB_SSL_ERROR callbacks. The data structure used is as follows:

typedef struct {
    char   *url;
    int     response;
} PtWebClient2SSLResponse_t;

The members include:

url

A pointer to the URL obtained from the Pt_CB_WEB_SSL_ERROR callback.

response

The type of response:

• Pt_WEB_RESPONSE_OK — override the error and continue.
• Pt_WEB_RESPONSE_CANCEL — abort the transaction.

Pt_ARG_WEB_STARTUP_ERRNO (read only)

A read-only resource that you can use to determine if the server started successfully. If the value isn't EOK, use errno to determine what went wrong. For more information, see “Starting the server,” above.

Pt_ARG_WEB_STOP (write only)

This is a write-only resource without any specified type. Set it to any value to stop the loading of the current page:

PtSetArg (&args[0], Pt_ARG_WEB_STOP, 0, 0);
PtSetResources (widget, 1, args);

Pt_ARG_WEB_UNKNOWN_RESP (write-only)

Set this resource to give a response to the server after a Pt_CB_WEB_UNKNOWN callback. When the downloading begins, the browser engine calls your Pt_CB_WEB_DOWNLOAD callback.

The data structure used is as follows:

typedef struct {
    short   response;
    short   zero;
    int     download_ticket;
    char   *filename;
    char   *url;
} PtWebClient2UnknownData_t;

The members include:

response

The type of response:

• Pt_WEB_RESPONSE_OK — the filename file is valid; continue with the disk download. Pt_CB_WEB_DOWNLOAD is called.
• Pt_WEB_RESPONSE_CANCEL — cancel the downloading of the unknown file.

download_ticket

Arbitrary data. You can set this to unique data to help you keep track of downloads, for example if several downloads happen concurrently.

filename

A pointer to the name of the file in which to save unknown data.

url

A pointer to the URL obtained from the Pt_CB_WEB_UNKNOWN callback.

Pt_ARG_WEB_VERSION (read only)

Get the value of this resource to obtain the version of the connected web server.

Pt_CB_WEB_AUTHENTICATE

A list of PtCallback_t structures that define the callbacks invoked when the server requires authentication information or when canceling a previous authentication request. To return the information, set the Pt_ARG_WEB_AUTHENTICATE resource.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_AUTHENTICATE

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebAuthenticateCallback_t structure:

typedef struct {
    short    type;
    short    action;
    char    *realm;
    char    *url;
} PtWebAuthenticateCallback_t;

The members of the PtWebAuthenticateCallback_t structure are:

type

The type of authentication used:

• Pt_WEB_BASIC_AUTHENTICATION
• Pt_WEB_DIGEST_AUTHENTICATION
• Pt_WEB_PROXY_AUTHENTICATION
• Pt_WEB_IMPORT_CERT_AUTHENTICATION

action

The action to take:

• Pt_WEB_ACTION_OK — the server is requesting basic authentication information.
• Pt_WEB_ACTION_ABORT — the server is canceling a previous request for basic authentication information.

realm

A pointer to the realm name.

url

A pointer to the URL that requires the authentication.

Pt_CB_WEB_CLOSE_WINDOW

A list of PtCallback_t structures that define the callbacks invoked when a web page with Javascript requests that its window be closed.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_CLOSE_WINDOW

reason_subtype

Not used.

event

NULL

cbdata

NULL

Pt_CB_WEB_COMPLETE

A list of PtCallback_t structures that define the callbacks invoked when the page has completed loading. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_COMPLETE

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebCompleteCallback_t structure:

typedef struct {
    char    *url;
} PtWebCompleteCallback_t;

The url member points to the URL of the page that has just completed.

Pt_CB_WEB_CONTEXT

A list of PtCallback_t structures that define the callbacks invoked when the user right-clicks on the current page with the mouse.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_CONTEXT

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebContextCallback_t structure:

typedef struct {
    long        context;
    PhPoint_t   pos;
} PtWebContextCallback_t;

The members of the PtWebContextCallback_t structure are:

context

The context, which is one of:

• Pt_WEB_CONTEXT_ANCHOR — the URL of a link is available.
• Pt_WEB_CONTEXT_OBJECT — the URL of an image or embedded object is available.
• Pt_WEB_CONTEXT_BKGD — the URL of a background image is available.

pos

A PhPoint_t structure (see the Photon Library Reference) that contains the (x, y) coordinates of the location where the right mouse button was pressed.

Pt_CB_WEB_DATA_REQ

Voyager server only.

A list of PtCallback_t structures that define the callbacks invoked when a file has been requested using the client protocol in the URL (e.g. client:about). The callback notifies the client that the server is waiting for data; to return the data, set the Pt_ARG_WEB_DATA resource.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_DATA_REQ

reason_subtype

The same as the type member in the callback data.

event

NULL

cbdata

A pointer to a PtWebDataReqCallback_t structure:

typedef struct {
    int     type;
    int     length;
    char   *url;
} PtWebDataReqCallback_t;

The members of the PtWebDataReqCallback_t structure are:

type

The type of request:

• Pt_WEB_DATA_HEADER — the server is requesting the header portion of the data. The header is of the same form present in an HTTP request header.
• Pt_WEB_DATA_BODY — the server is requesting the body portion of the data.
• Pt_WEB_DATA_CLOSE — the server has closed the data stream, and no more data should be given to the server.

length

The maximum amount of data the server can accept, in bytes.

url

A pointer to the URL of the request.

For an example of using the client protocol, see Pt_ARG_WEB_DATA.

Pt_CB_WEB_DOWNLOAD

A list of PtCallback_t structures that define the callbacks invoked when the browser begins a file download.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_DOWNLOAD

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebDownloadCallback_t structure:

typedef struct {
  int download_ticket;
  int type;
  int current;
  int total;
  char *url;
  char *message;
} PtWebDownloadCallback_t;

The members of the PtWebDownloadCallback_t structure are:

download_ticket

This is the download_ticket assigned to the download when you set the PtWebClient2UnknownData_t structure for the Pt_ARG_WEB_UNKNOWN_RESP resource. This ticket allows you to keep track of multiple downloads.

type

Can be one of:

• Pt_WEB_DOWNLOAD_ERROR — an error occurred; display a dialog with some error text (see message).
• Pt_WEB_DOWNLOAD_DONE — the download is complete.
• Pt_WEB_DOWNLOAD_PROGRESS — the download is in progress.

current

The current number of bytes that have been downloaded.

total

The total expected number of bytes.

url

The URL of the downloaded file.

message

A descriptive message of the error that has occurred. The message is used only when type is Pt_WEB_DOWNLOAD_ERROR.

Pt_CB_WEB_ERROR

A list of PtCallback_t structures that define the callbacks invoked if an error occurs while loading a page. This includes unknown URL protocols such as mailto:, allowing the client to handle them.

---

The mailto links are handled by the client. This is done by watching for the mailto URL in the Pt_CB_WEB_ERROR callback.

---

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_ERROR

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebErrorCallback_t structure:

typedef struct {
    short    type;
    short    reason;
    char    *url;
    char    *description;
} PtWebErrorCallback_t;

The members of the PtWebErrorCallback_t structure are:

type

The type of error:

• Pt_WEB_ERROR_SERVER_EXIT — the server has terminated.
• Pt_WEB_ERROR_TOPVIEW — an error occurred when loading the requested page.
• Pt_WEB_ERROR_SUBVIEW — an error occurred when loading a subdocument of the requested page (e.g. images in an HTML page).
• Pt_WEB_ERROR_FILE — an error occurred when saving a document to disk.
• Pt_WEB_ERROR_WML — an error occurred when loading the requested WML page.

reason

If type is Pt_WEB_ERROR_SERVER_EXIT, the reason member contains the terminating status of the server (use waitpid () to determine why the server terminated).

If type is Pt_WEB_ERROR_WML, an error occurred in WML content, and the reason member contains one of:

Pt_WEB_ERROR_WML_AccessDenied

Access rejection error caused by specifying an access element.

Pt_WEB_ERROR_WML_InvalidVariableReference

Incorrect variable name error.

Pt_WEB_ERROR_WML_InfiniteLoop

The WML parser has detected an infinite loop.

Pt_WEB_ERROR_WML_Unknown

An unknown WML error has occurred.

Pt_WEB_ERROR_WML_SAX

The WML parser has detected a syntax error.

For other values of type, the possible values of reason are:

-1

Unspecified or unknown error.

-2

Parameter check / consistency check failed.

-3

Low memory.

-4

Low image-cache memory.

-5

The operation was aborted.

-6

Bad header.

-8

The document contains no data.

-9

Missing service API.

-10

Missing request API.

-11

Multiple initialization.

-12

DNS failure.

-13

Connection failure.

-14

Network failure.

-15

Bad input stream.

-16

Request for data sink failed.

-17

New data sink failed.

-18

Invalid redirect.

-19

Unknown server error.

-21

Unknown document character-set encoding.

-31

Corrupt data.

-39

Helper failed.

-40

SSL not supported.

-41

Unknown URL (No URL handler could be found to process the given URL).

-400

HTTP — Bad request.

-401

HTTP — Unauthorized.

-402

HTTP — Payment required.

-403

HTTP — Forbidden.

-404

HTTP — Not found.

-405

HTTP — Method not allowed.

-406

HTTP — Not acceptable.

-407

HTTP — Proxy authentication required.

-408

HTTP — Request time-out.

-409

HTTP — Conflict.

-410

HTTP — Gone.

-411

HTTP — Length required.

-412

HTTP — Precondition required.

-413

HTTP — Request entity is too large.

-414

HTTP — Request URL too is large.

-415

HTTP — Unsupported media type.

-500

HTTP — Internal server error.

-501

HTTP — Not implemented.

-502

HTTP — Bad gateway.

-503

HTTP — Service unavailable.

-504

HTTP — Gateway time-out.

-505

HTTP — HTTP version not supported.

-1200

FTP — Server error.

-1202

FTP — Error 332.

-1203

FTP — Error 530.

description

The netfront server sets this member to a string containing a description of the error.
Voyager server does not use this member, and sets it to NULL.

Pt_CB_WEB_IMPORT_CERTIFICATE

A list of PtCallback_t structures that define the callbacks invoked to inform the client whether a client certificate import operation is successful. The client initiates the import by setting Pt_ARG_WEB_IMPORT_CERTIFICATE

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_IMPORT_CERTIFICATE.

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebImportCertificateCallback_t structure:

typedef struct {
  int reason;
  char *description;
  } PtWebImportCertificateCallback_t;

The reason is one of:

• Pt_WEB_IMPORT_CERTIFICATE_OK
• Pt_WEB_IMPORT_CERTIFICATE_ERROR

If reason is Pt_WEB_IMPORT_CERTIFICATE_ERROR, description is a textual explanation for the error.

Pt_CB_WEB_METADATA

A list of PtCallback_t structures that define the callbacks invoked to inform the client of metadata that was read from the page. The only metadata currently returned is the web page title.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_METADATA

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebMetaDataCallback_t structure:

typedef struct {
    char    *url;
    char    *name;
    char    *value;
} PtWebMetaDataCallback_t;

The members include the following:

url

The page URL.

name

The metadata name; currently only title is supported.

value

The metadata value.

Here's an example of using Pt_CB_WEB_METADATA to set a window widget's title to the HTML page title (web_curr_title is a global variable):

int web_title( PtWidget_t *widget, ApInfo_t *apinfo,
               PtCallbackInfo_t *cbinfo )
{
    PtWebMetaDataCallback_t *cb = cbinfo->cbdata;
    PtArg_t                 args[1];

    if ( !strcmp( cb->name, "title" ) ) {
        if ( web_curr_title )
            free( web_curr_title );
        web_curr_title = strdup( cb->value );
        PtSetArg( &args[0], Pt_ARG_WINDOW_TITLE, cb->value, 0 );
        PtSetResources( ABW_base, 1, args );
    }

    return( Pt_CONTINUE );
}

Pt_CB_WEB_NEED_SCROLL (key mode only)

Voyager server only.

A list of PtCallback_t structures that define the callbacks invoked when the server requires the client to scroll the page.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_NEED_SCROLL

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebNeedScrollCallback_t structure:

typedef struct {
    short    dir;
} PtWebNeedScrollCallback_t;

where dir indicates the direction to scroll:

• Pt_WEB_DIRECTION_UP
• Pt_WEB_DIRECTION_DOWN
• Pt_WEB_DIRECTION_LEFT
• Pt_WEB_DIRECTION_RIGHT

Pt_CB_WEB_NEW_WINDOW

A list of PtCallback_t structures that define the callbacks invoked when the browser requests that a new PtWebClient widget be connected to the server so that it can display a page.

If no callback is attached, then the requested page appears in the window that the request was made (i.e. the one the user clicked in). This doesn't apply to Javascript open windows.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_NEW_WINDOW

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebWindowCallback_t structure:

typedef struct {
    PhDim_t     size;
    long        flags;
} PtWebWindowCallback_t;

The members of the PtWebWindowCallback_t structure are:

size

A PhDim_t structure (see the Photon Library Reference) that defines the dimensions of the new window.

flags

A combination of the following bits:

• Pt_WEB_SHOW_TOOLBAR — if the client contains a toolbar, it should be visible.
• Pt_WEB_SHOW_MENUBAR — if the client contains a menubar, it should be visible.
• Pt_WEB_RESIZEABLE — the new window should be resizable.
• Pt_WEB_SHOW_STATUS — the status field should be visible.
• Pt_WEB_SHOW_LOCATION — the URL location text field should be visible.

Pt_CB_WEB_PAGE_INFO

A list of PtCallback_t structures that define the callbacks invoked when the page size or position has changed. Each callback is passed a PtCallbackInfo_t structure that contains at least:

reason

Pt_CB_WEB_PAGE_INFO

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebPageInfoCallback_t structure:

typedef struct {
    long    vheight;
    long    vwidth;
    long    height;
    long    width;
    long    ypos;
    long    xpos;
} PtWebPageInfoCallback_t;

The members of the PtWebPageInfoCallback_t structure are:

vheight

The height of the visible portion, in pixels.

vwidth

The width of the visible portion, in pixels.

height

The height of the page, in pixels.

width

The width of the page, in pixels.

ypos

The position of the right side of the page, in pixels.

xpos

The position of the top of the page, in pixels.

Pt_CB_WEB_SSL_CERTINFO

A list of PtCallback_t structures that define the callbacks that are invoked when the web server has discovered an SSL connection; invoked after the handshake phase has determined the other party's identity.

---

This callback list is invoked only if you're using the SSL version of the Voyager server (Spyrus Terisa version).

---

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_SSL_CERTINFO

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebSSLCertInfoCallback_t structure:

typedef struct PtWebSSLCertInfoCallback_t {
    char           *url;
    char           *cipher_kind;
    int             is_sgc;
    int             version;
    unsigned int    flags;
    struct {
        char       *serial;
        char       *subject;
        char       *issuer;
    }               certinfo;
    time_t  valid_begin, valid_end;
    char   *status;
    char   *extensions;
} PtWebSSLCertInfoCallback_t;

The members of the PtWebSSLCertInfoCallback_t structure are:

url

A pointer to the URL associated with the error.

cipher_kind

A pointer to the cipher suite used for the connection (SSL_3_RSA_WITH_RC4-128_MD5, SSL_3_RSA_WITH_RC4_40_MD5, etc.)

is_sgc

Nonzero if the connection is using the “Server Gated Cryptography” (also called “Step-Up Encryption”).

version

The version number: 2 for SSL 2.0, 0x0300 (768) for SSL 3.0, 0x0301 for TLS 1.0.

flags

Flags for future extensions (always zero in the current implementation).

certinfo.serial

A pointer to the serial number for the certificate (a hexadecimal number).

certinfo.subject, certinfo.issuer

A pointer to distinguished names of the public key being certified.

valid_begin, valid_end

The time (in seconds since 01/01/1970 0h UTC) at which the certificates became valid and invalid.

status

A pointer to the status of the certificate, represented as a string (Valid, Pending, Expired, Trusted root, Unverified, and so on).

extensions

A pointer to some additional information about the SSL connections (string).

When this callback is invoked, typically the client saves this information relative to the current SSL connection, in order to be able to display it on a subsequent user's request (usually when the user clicks on the lock).

these callbacks should return only Pt_CONTINUE; there's no need to fill up a special structure as response.

Pt_CB_WEB_SSL_CERTNONTRUSTED

A list of PtCallback_t structures that define the callbacks that are invoked when the web server has discovered that the current SSL connection is made with a nontrusted certificate. Note that Voyager supports only server certificates, and not Client certificates.

---

This callback list is invoked only if you're using the SSL version of the Voyager server (Spyrus Terisa version).

---

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_SSL_CERTNONTRUSTED

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebSSLCertNonTrustedCallback_t structure:

typedef struct {
  short action;
  short ncert;
  char  *url;
  char  *status;
  int   reason;
  PtWebSSLCertInfo_t info[1];
  } PtWebSSLCertNonTrustedCallback_t;

The members of the PtWebSSLCertNonTrustedCallback_t structure are:

action

One of the following:

• Pt_WEB_ACTION_OK—the callback was invoked as a warning; The non- trusted certificate didn't make the connection to be aborted.
• Pt_WEB_ACTION_ABORT—the connection was aborted.

ncert

The number of items in the info array.

url

A pointer to the URL associated with the error.

status

A pointer to the status of the certificate, represented as a string (Valid, Pending, Expired, Trusted root, Unverified, and so on).

info

An array of PtWebSSLCertInfo_t structures (see below).

reason

The reason the callback was invoked. Can be one of:

• Pt_WEB_SSL_AUTHENTICATE — the callback was invoked during an authentication.
• Pt_WEB_SSL_IMPORT_CERT — the callback was invoked during an import-certificate operation.

typedef struct {
  char *name;
  char *subject;
  char *issuer;
  char *cert_serial;
  char *version;
  char *signature_algorithm;
  char *basic_constraints;
  char *extended_key_usage;
  int rsa_public_key_bits;
  time_t  valid_begin, valid_end;
  } PtWebSSLCertInfo_t;
  

PtWebSSLCertInfo_t has these members:

name

A pointer to the certificate's name.

subject, issuer

A pointer to distinguished names of the public key being certified.

cert_serial

A pointer to the serial number for the certificate (hexadecimal number).

version

The version of X.509 applied to the certificate (1, 2, or 3).

signature_algorithm

The signature algorithm, which can be one of:

• CRL_SIGN_ALGO_RSA — RSA Encryption
• CRL_SIGN_ALGO_MD2_WITH_RSA — MD2 with RSA Encryption
• CRL_SIGN_ALGO_MD5_WITH_RSA — MD5 with RSA Encryption
• CRL_SIGN_ALGO_SHA1_WITH_RSA — SHA-1 with RSA Encryption
• CRL_SIGN_ALGO_SHA1_WITH_RSA_SIGN — SHA-1 with RSA Signature

basic_constraints

Basic constraints for the certificate.

extended_key_usage

The extended key usage, which specifies the uses for which a certificate is valid.

rsa_public_key_bits

The number of bits in the public RSA key.

valid_begin, valid_end

The times (in seconds since 01/01/1970 0h UTC) at which the certificates became valid and invalid.

When this callback is invoked, typically the client displays a dialog giving three choices to the user:

• Abort
• Continue
• Accept.

The transaction is halted until you set the Pt_ARG_WEB_SSL_RESPONSE resource. You need to fill in a PtWebClient2SSLResponse_t structure with the URL found in the callback structure and one of these response codes:

Pt_WEB_RESPONSE_CANCEL

Abort the connection to the site.

Pt_WEB_RESPONSE_CONTINUE

Connect to the site, but don't save the certificate.

Pt_WEB_RESPONSE_OK

Connect to the site, and save the certificate.

Pt_CB_WEB_SSL_CLIENT_CERT_SELECT

A list of PtCallback_t structures that define the callbacks that are invoked when the netfront server wants the browser client to display a client- certificate-selection dialog. The dialog should list the available client certificates and the user should select one certificate to be used for the current URL that requested it.

The transaction is halted until you set the Pt_ARG_WEB_SSL_RESPONSE resource. You need to fill in a PtWebClient2SSLResponse_t structure with the url found in the callback structure and you have to set the response field to the index (starting at 0) of the selected certificate.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_SSL_CLIENT_CERT_SELECT

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebSSLClientCertCallback_t structure:

typedef struct {
  int ncert;
  char *url;
  int reserved1;
  int reserved2;
  PtWebSSLCertInfo_t *info;
  } PtWebSSLClientCertCallback_t;

The members of the PtWebSSLClientCertCallback_t structure include:

ncert

The number of certificates to be displayed (the number of items in the info array).

url

The current URL that have requested the client certificates selection dialog to be displayed.

info

An array of information about the certificates. See the Pt_CB_WEB_SSL_CERTNONTRUSTED resource for a description of the PtWebSSLCertInfo_t structure.

Pt_CB_WEB_SSL_ERROR

A list of PtCallback_t structures that define the callbacks that are invoked when the Voyager server has discovered an error or inconsistency with the current SSL transaction.

---

This callback list is invoked only if you're using the SSL version of the Voyager server (Spyrus Terisa version).

---

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_SSL_ERROR

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebSSLErrorCallback_t structure:

typedef struct {
  short  certerr;
  short  trusted;
  char   *url;
  int    reason;
} PtWebSSLErrorCallback_t;

The members of the PtWebSSLErrorCallback_t structure are:

• trusted — indicates whether the current certificate is trusted.
• url — a pointer to the URL associated with the error.
• reason — one of:
  • Pt_WEB_SSL_AUTHENTICATE — the callback is invoked during an authentication.
  • Pt_WEB_SSL_IMPORT_CERT — the callback is invoked during an import certificate operation.
• certerr — one of the following:

  Pt_WEB_ERROR_CertNoError

  You don't have a trusted certification on your end.

  Pt_WEB_ERROR_CertChainInvalid

  No correct server should provide a certificate chain that causes this error. Any chain that creates this error is entirely insecure. Therefore, this error can't be overridden.

  Pt_WEB_ERROR_CertExpired

  The certificate provided by the remote server has expired.

  Pt_WEB_ERROR_CertNamesNotEqual

  The name in the certificate isn't the same as its DNS name.

  Pt_WEB_ERROR_CertChainIncomplete

  This error can be overridden and is equivalent to receiving a certificate with an unknown and untrusted root certificate. If you choose to override this error, you abandon any protection from active attacks, but, because this error can be caused by a server with a valid certificate (albeit one issued by an unknown party), letting users override this error may let them connect to a valid site they would otherwise be unable to access.

  Pt_WEB_ERROR_InvalidSignature

  Like Pt_WEB_ERROR_CertChainInvalid, this error can't be overridden.

  Pt_WEB_ERROR_BasicConstraints

  Violates basic constraints.

  Pt_WEB_ERROR_FailedVerify

  Cannot verify the signature.

  Pt_WEB_ERROR_IncorrectKeyUsage

  Key use and extension key use are invalid.

  Pt_WEB_ERROR_RootCertificateNotValid

  The browser's root CA certificate is expired.

The transaction is halted until you set the Pt_ARG_WEB_SSL_RESPONSE resource. You need to fill in a PtWebClient2SSLResponse_t structure with the URL found in the callback structure and one of the following response codes:

• Pt_WEB_RESPONSE_OK — override the error and continue.
• Pt_WEB_RESPONSE_CANCEL — abort the transaction.

Pt_CB_WEB_START

A list of PtCallback_t structures that define the callbacks invoked when a page starts loading. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_START

reason_subtype

Not used.

event

NULL

cbdata

NULL

Pt_CB_WEB_STATUS

A list of PtCallback_t structures that define the callbacks that are invoked when the browser's status changes. These callbacks give you many different types of information.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_STATUS

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebStatusCallback_t structure:

typedef struct {
    short   type;
    short   zero;
    char   *desc;
    char   *url;
} PtWebStatusCallback_t;

This callback gives you many different types of information. Before performing any actions, you should first check the type and then act accordingly.

The types are:

Pt_WEB_STATUS_MOUSE

Reports when the mouse moved over links, images, etc.

Pt_WEB_STATUS_CONNECT

Reports connection-related messages.

Pt_WEB_STATUS_DEFAULT

Reported when Javascript requests the default status bar text be changed (i.e. window.defaultStatus="…"). The defaultStatus message appears when nothing else is in the status bar.

Pt_WEB_STATUS_PROGRESS

A progress message (e.g. the number of bytes downloaded).

Pt_WEB_STATUS_INFO

Reports various information. Valid INFO types are:

FORM-EDIT

Single-line text field has focus.

FORM-PASS

The password field has focus.

FORM-LIST

Single-select list has focus.

FORM-MULTILIST

Multi-select list has focus.

FORM-COMBO

Combo box has focus.

FORM-TEXTAREA

Multi-line text field has focus.

FORM-CHECKBOX

Check box has focus.

FORM-RADIO

Radio button has focus.

FORM-SUBMIT

Submit button has focus.

FORM-RESET

Reset button has focus.

LINK-IMAGE-MAP

Image map has focus.

LINK-IMAGE

Image link has focus.

LINK-TEXT

Text link has focus.

FRAMESET-DOC

Frames document has been loaded.

FORM-CURSOR-LEFT

The cursor inside a FORM control or image map has reached the leftmost position.

FORM-CURSOR-RIGHT

The cursor inside a FORM control or image map has reached the rightmost cursor position.

FORM-CURSOR-TOP

The cursor inside a FORM control or image map has reached the topmost position.

FORM-CURSOR-BOTTOM

The cursor inside a FORM control or image map has reached the bottommost cursor position.

PAGE-TOP

The page has scrolled to its topmost position.

PAGE-BOTTOM

The page has scrolled to its bottommost position.

PAGE-LEFT

The page has scrolled to its leftmost position.

PAGE-RIGHT

The page has scrolled to its rightmost position.

Pt_WEB_STATUS_PRINT

Reports print-related status (pages printed):

• "Print Error %d" — an error occurred. The %d parameter can be:

  -600

  No printer was set.

  -601

  The page wasn't printable.

  -602

  A general printing error occurred.

• "Print Done"
• "Print Done - More" — more pages can be printed.

Pt_WEB_STATUS_CONTENTS

Reports when a single-line text field, password, or text area control receives focus on the page. The information passed in the description field is a string containing an ordinal number identifying the control on the web page, followed by a colon, followed by the contents of the text field that just got focus.

Pt_CB_WEB_UNKNOWN

A list of PtCallback_t structures that define the callbacks invoked when the server has received a file that it can't display or has no external helpers that match its mimetype or file suffix. Set Pt_ARG_WEB_UNKNOWN_RESP to provide a filename or cancel the download anytime after this callback.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_UNKNOWN

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebUnknownCallback_t structure:

typedef struct {
    short    action;
    short    flags;
    char    *content_type;
    int      content_length;
    char    *url;
} PtWebUnknownCallback_t;

The members of the PtWebUnknownCallback_t structure are:

action

The action taking place:

• Pt_WEB_ACTION_OK — the server is requesting a the name of a file in which to save the data.
• Pt_WEB_ACTION_ABORT — the server is canceling a previous request for a filename.

flags

Not currently used.

content_type

A pointer to the mime content type of the file (if available).

content_length

The length of the file (-1 if unknown).

url

A pointer to the URL of the file.

Pt_CB_WEB_URL

A list of PtCallback_t structures that define the callbacks that are invoked when the browser has a complete URL to be loaded. This is useful for saving internal history lists or saving URLs in hotlists.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_WEB_URL

reason_subtype

Not used.

event

NULL

cbdata

A pointer to a PtWebUrlCallback_t structure:

typedef struct {
    char   *url;
} PtWebUrlCallback_t;

Inherited resources:

If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.

Caveats:

Calling PtWidgetToFront() or PtWidgetToBack() on a PtWebClient widget has no effect. This is because the PtWebServer widget is in a different application. Moving a widget in one application cannot cause draw events that are emitted from a different application's region to be clipped. If you do not wish to display the PtWebClient, you should unrealize it using the PtUnrealizeWidget API call.