PtWebClient

`PtWebClient`

Widget for displaying web pages

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtClient --> PtWebClient

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

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 vserver and netfront in the QNX Neutrino Utilities Reference.

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:

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.
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:

Resource	C type	Pt type	Default
Pt_ARG_WEB_ACTIVATE_LINK	`int`	Scalar	0 (write-only)
Pt_ARG_WEB_AUTHENTICATE	See below	Pointer	NULL (write-only)
Pt_ARG_WEB_BUILD_DATE	`char *`	String	NULL (read-only)
Pt_ARG_WEB_COMMAND	`PtWebCommand_t *`	Pointer	NULL (write-only)
Pt_ARG_WEB_DATA	`PtWebClientData_t *`	Pointer	NULL (write-only)
Pt_ARG_WEB_DOWNLOAD	`char `, `char `	String	N/A (write-only)
Pt_ARG_WEB_ENCODING	`char *`	String	NULL
Pt_ARG_WEB_GET_CERTIFICATES	See below	Pointer	NULL (read-only)
Pt_ARG_WEB_GET_CONTEXT	`char *`	String	NULL (read-only)
Pt_ARG_WEB_GET_HISTORY	See below	Pointer	None (read-only)
Pt_ARG_WEB_GET_URL	`char *`	String	N/A (write-only)
Pt_ARG_WEB_HELPER	See below	Pointer	NULL (write-only)
Pt_ARG_WEB_H_ERRNO	`int`	Scalar	0
Pt_ARG_WEB_IMPORT_CERTIFICATE	See below	Pointer	N/A (write-only)
Pt_ARG_WEB_NAVIGATE_FRAME	`int`	Scalar	0
Pt_ARG_WEB_NAVIGATE_LINK	`int`	Scalar	0
Pt_ARG_WEB_NAVIGATE_PAGE	`int`	Scalar	0
Pt_ARG_WEB_OPTION	`char `, `char`	String	NULL
Pt_ARG_WEB_PRINT	`PpPrintContext_t *`, `int`	Pointer	NULL (write-only)
Pt_ARG_WEB_RELOAD	N/A	N/A	N/A (write-only)
Pt_ARG_WEB_SERVER	`char *`	String	NULL
Pt_ARG_WEB_SERVER_PID	`pid_t`	Scalar	read-only
Pt_ARG_WEB_SSL_RESPONSE	See below	Pointer	NULL
Pt_ARG_WEB_STARTUP_ERRNO	`int`	Scalar	0
Pt_ARG_WEB_STOP	N/A	N/A	N/A (write-only)
Pt_ARG_WEB_UNKNOWN_RESP	See below	Pointer	NULL (write-only)
Pt_ARG_WEB_VERSION	`char *`	String	NULL (read-only)
Pt_CB_WEB_AUTHENTICATE	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_CLOSE_WINDOW	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_COMPLETE	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_CONTEXT	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_DATA_REQ	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_DOWNLOAD	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_ERROR	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_IMPORT_CERTIFICATE	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_METADATA	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_NEED_SCROLL	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_NEW_WINDOW	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_PAGE_INFO	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_SSL_CERTINFO	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_SSL_CERTNONTRUSTED	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_SSL_CLIENT_CERT_SELECT	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_SSL_ERROR	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_START	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_STATUS	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_UNKNOWN	`PtCallback_t *`	Link	NULL
Pt_CB_WEB_URL	`PtCallback_t *`	Link	NULL

Pt_ARG_WEB_ACTIVATE_LINK (key mode only)

C type	Pt type	Default
`int`	Scalar	0 (write-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

C type	Pt type	Default
`PtWebClientAuthenticationData_t *`	Pointer	NULL (write-only)

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;
} PtWebClientAuthenticationData_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)

C type	Pt type	Default
`char *`	String	NULL (read-only)

The build date of the connected web server.

Pt_ARG_WEB_COMMAND (write only)

C type	Pt type	Default
`PtWebCommand_t *`	Pointer	NULL

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

The PtWebCommand_t data structure is as follows:

typedef struct {
    union {
        struct {
            char   *filename;
        } SaveasInfo;
        struct {
            char *String;
            unsigned long flags;
        } FindInfo;
        char   *scroll_to;
        int     reset_type;
        int     num_purge;
    };
} PtWebCommand_t;

The commands are:

Pt_WEB_COMMAND_FIND

Find and highlight a word in the current document. The part of the PtWebCommand_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 PtWebCommand_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_ARG_WEB_DATA (write only)

C type	Pt type	Default
`PtWebClientData_t *`	Pointer	NULL

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;
} PtWebClientData_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];
    PtWebClientData_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)

C type	Pt type	Default
`char `, `char `	String	N/A

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

C type	Pt type	Default
`char *`	String	NULL

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)

C type	Pt type	Default
`PtWebSSLClientCertificates_t *`	Pointer	NULL

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)

C type	Pt type	Default
`char *`	String	NULL

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)

C type	Pt type	Default
`PtWebClientHistory_t *`	Pointer	None

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)

C type	Pt type	Default
`char *`	String	N/A

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:

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)

C type	Pt type	Default
`PtWebClientHelperData_t *`	Pointer	NULL

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;
} PtWebClientHelperData_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

C type	Pt type	Default
`int`	Scalar	0

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

C type	Pt type	Default
`PtWebImportCertificate_t`	Pointer	0

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

C type	Pt type	Default
`int`	Scalar	0

Voyager server only.

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

C type	Pt type	Default
`int`	Scalar	0

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.

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

C type	Pt type	Default
`int`	Scalar	0

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

C type	Pt type	Default
`char `, `char`	String	NULL

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 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

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"

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 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".

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"

fFitIntoPane

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"

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"

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)

C type	Pt type	Default
`PpPrintContext_t *`, `int`	Pointer

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)

C type	Pt type	Default
N/A	N/A	N/A

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

C type	Pt type	Default
`char *`	String	NULL

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)

C type	Pt type	Default
`pid_t`	Scalar

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

C type	Pt type	Default
`PtWebClient2SSLResponse_t *`	Pointer	NULL

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)

C type	Pt type	Default
`int`	Scalar	0

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)

C type	Pt type	Default
N/A	N/A	N/A

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)

C type	Pt type	Default
`PtWebClientUnknownData_t *`	Pointer

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;
} PtWebClientUnknownData_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)

C type	Pt type	Default
`char *`	String

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

Pt_CB_WEB_AUTHENTICATE

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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 PtWebClientUnknownData_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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

A list of PtCallback_t structures that define the callbacks invoked to inform the client of meta data that was read from the page. The most common meta data 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 name member for the web page title is title.

Pt_CB_WEB_NEED_SCROLL (key mode only)

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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.

Pt_WEB_RESPONSE_OK -- override the error and continue.
Pt_WEB_RESPONSE_CANCEL -- abort the transaction.

Pt_CB_WEB_START

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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_CB_WEB_UNKNOWN

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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

C type	Pt type	Default
`PtCallback_t *`	Link	NULL

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.

Resource	Inherited from	Default override
Pt_ARG_ANCHOR_FLAGS	`PtWidget`
Pt_ARG_ANCHOR_OFFSETS	`PtWidget`
Pt_ARG_AREA	`PtWidget`
Pt_ARG_BANDWIDTH_THRESHOLD	`PtBasic`	Not used by this class.
Pt_ARG_BASIC_FLAGS	`PtBasic`
Pt_ARG_BEVEL_WIDTH	`PtWidget`	0
Pt_ARG_BITMAP_CURSOR	`PtWidget`
Pt_ARG_BEVEL_COLOR	`PtBasic`
Pt_ARG_BEVEL_CONTRAST	`PtBasic`
Pt_ARG_CLIENT_FLAGS	`PtClient`
Pt_ARG_CLIENT_NAME	`PtClient`	`"VoyagerServer-2"`
Pt_ARG_CLIENT_REPLY_LEN	`PtClient`
Pt_ARG_CLIENT_SEND	`PtClient`
Pt_ARG_CLIENT_SERVER	`PtClient`
Pt_ARG_COLOR	`PtBasic`
Pt_ARG_CONTAINER_FLAGS	`PtContainer`
Pt_ARG_CONTRAST	`PtBasic`
Pt_ARG_CURSOR_COLOR	`PtWidget`
Pt_ARG_CURSOR_OVERRIDE	`PtContainer`
Pt_ARG_CURSOR_TYPE	`PtWidget`
Pt_ARG_DARK_BEVEL_COLOR	`PtBasic`
Pt_ARG_DARK_FILL_COLOR	`PtBasic`
Pt_ARG_DATA	`PtWidget`
Pt_ARG_DIM	`PtWidget`
Pt_ARG_EFLAGS	`PtWidget`
Pt_ARG_EXTENT	`PtWidget`
Pt_ARG_FILL_COLOR	`PtBasic`
Pt_ARG_FILL_PATTERN	`PtBasic`
Pt_ARG_FLAGS	`PtWidget`
Pt_ARG_HEIGHT	`PtWidget`
Pt_ARG_HELP_TOPIC	`PtWidget`
Pt_ARG_HIGHLIGHT_ROUNDNESS	`PtBasic`
Pt_ARG_INLINE_COLOR	`PtBasic`
Pt_ARG_LIGHT_BEVEL_COLOR	`PtBasic`
Pt_ARG_LIGHT_FILL_COLOR	`PtBasic`
Pt_ARG_MARGIN_HEIGHT	`PtBasic`
Pt_ARG_MARGIN_WIDTH	`PtBasic`
Pt_ARG_MAXIMUM_DIM	`PtWidget`
Pt_ARG_MINIMUM_DIM	`PtWidget`
Pt_ARG_OUTLINE_COLOR	`PtBasic`
Pt_ARG_POINTER	`PtWidget`
Pt_ARG_POS	`PtWidget`
Pt_ARG_RESIZE_FLAGS	`PtWidget`
Pt_ARG_STYLE	`PtBasic`
Pt_ARG_TITLE	`PtContainer`
Pt_ARG_TITLE_FONT	`PtContainer`
Pt_ARG_TRANS_PATTERN	`PtBasic`
Pt_ARG_USER_DATA	`PtWidget`
Pt_ARG_WIDTH	`PtWidget`
Pt_CB_ACTIVATE	`PtBasic`
Pt_CB_ARM	`PtBasic`
Pt_CB_BALLOONS	`PtContainer`
Pt_CB_BLOCKED	`PtWidget`
Pt_CB_CHILD_ADDED_REMOVED	`PtContainer`
Pt_CB_CLIENT_CONNECTED	`PtClient`
Pt_CB_CLIENT_EVENT	`PtClient`
Pt_CB_CLIENT_NOT_FOUND	`PtClient`
Pt_CB_DESTROYED	`PtWidget`
Pt_CB_DISARM	`PtBasic`
Pt_CB_DND	`PtWidget`
Pt_CB_FILTER	`PtWidget`
Pt_CB_GOT_FOCUS	`PtBasic`
Pt_CB_HOTKEY	`PtWidget`
Pt_CB_IS_DESTROYED	`PtWidget`
Pt_CB_LOST_FOCUS	`PtBasic`
Pt_CB_MENU	`PtBasic`
Pt_CB_OUTBOUND	`PtWidget`
Pt_CB_RAW	`PtWidget`
Pt_CB_REALIZED	`PtWidget`
Pt_CB_REPEAT	`PtBasic`
Pt_CB_RESIZE	`PtContainer`
Pt_CB_UNREALIZED	`PtWidget`

Museum

PtWebClient