Widget for displaying web pages
PtWidget → PtBasic → PtContainer → PtClient → PtWebClient
For more information, see the diagram of the widget hierarchy.
<photon/PtWebClient.h>
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. |
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:
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.
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:
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:
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.
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 | PtWebClient2Command_t * | Pointer | NULL (write-only) |
Pt_ARG_WEB_DATA | PtWebClient2Data_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 |
C type | Pt type | Default |
---|---|---|
int | Scalar | 0 (write-only) |
This resource activates and deactivates the current link.
C type | Pt type | Default |
---|---|---|
PtWebClient2AuthenticationData_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; } PtWebClient2AuthenticationData_t;
The members include:
C type | Pt type | Default |
---|---|---|
char * | String | NULL (read-only) |
The build date of the connected web server.
C type | Pt type | Default |
---|---|---|
PtWebClient2Command_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 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:
struct { char *string; unsigned long flags; } FindInfo;
where:
struct { char *filename; } SaveasInfo;
where filename is a pointer to the name of the file in which to save the document.
struct { char *string; int number; } SetWidgetInfo;
where:
C type | Pt type | Default |
---|---|---|
PtWebClient2Data_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; } PtWebClient2Data_t;
The members are:
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 ); }
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. |
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.
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:
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:
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:
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; }
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:
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):
|
C type | Pt type | Default |
---|---|---|
PtWebClient2HelperData_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; } PtWebClient2HelperData_t;
The members of this structure are:
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.) |
C type | Pt type | Default |
---|---|---|
int | Scalar | 0 |
The value of h_errno after a DNS failure. The possible values are:
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:
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.
C type | Pt type | Default |
---|---|---|
int | Scalar | 0 |
Controls focus navigation of FRAMES pages when the browser is in key mode. Set the value argument of PtSetArg() to one of:
The next and previous directions are defined by the order of the <FRAME> tags in each <FRAMESET> tag. |
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:
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. |
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:
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 */ }
C type | Pt type | Default |
---|---|---|
char *, char* | String | NULL |
Set this resource to set options on the web server. This resource takes two parameters:
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:
The HTML options are:
Default: "#ff0000"
Default: "#0000ff"
Default: "#008080"
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"
Don't highlight text while dragging over it.
Default: "FALSE"
Disable drawing image placeholders for missing or invalid images.
Default: "FALSE"
If "TRUE", color attributes override what's specified in the page.
Default: "FALSE"
If set to "TRUE", key navigation is enabled.
Default: "FALSE"
Default: "#ffffff"
Default: "#000000"
Default: "10"
Default: "20"
The bottom color of borders in frame pages.
Default: "#606060"
The bottom color of the focus box in key mode.
Default: "#7f7f00"
Default: "TRUE"
Allow page source to be viewed. Setting this option to "FALSE" saves memory.
Default: "TRUE"
Default: "FALSE"
Default: "FALSE"
Activate links on arming (useful for touch screens).
Default: "FALSE"
Print background colors.
Default: "FALSE"
Default: "#9098F8"
The font used for lists, comboboxes, submit buttons and reset buttons.
The spacing between frames, in pixels.
Default: "2"
The font family name of the text used in headings on the page.
Reformat handling
Default: "2"
Possible values:
Default: "16"
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.
Disable Java applet tag parsing (forced "TRUE" if vgr_javanpl.so isn't found).
Default: "FALSE"
The font used for editable form fields.
The font family name used for preformatted text ( this should be a fixed-width font).
The top color of borders in frame pages.
Default: "#ffffff"
The top color of the focus box in key mode.
Default: "#ffff00"
The line thickness, in pixels, of the underline used on links.
Default: "1"
The HTTP cookie options are:
Default: "cookie.jar"
Default: "$(HOME)"
Always keep the cookie-jar file on disk up-to-date.
Default: "FALSE"
Default: "-1"
The authentication options are:
The maximum number of guesses allowed when performing authentication.
Default: "3"
The FTP options are:
The email address used for the password on anonymous logins on the FTP server.
Default: "80"
The host name or IP address of proxy server for FTP requests.
Default: none
The port number on the FTP proxy server to use.
Default: "80"
Default: "80"
The Gopher options are:
The host name or IP address of the proxy server for gopher requests.
Default: none
The port number on the gopher proxy server to use.
Default: "80"
Default: none
The HTTP options are:
Default: none
Default: "80"
Default: none
The file options are:
Display directory listings as HTML pages. For example, file:/ produces an HTML page with the content of the root directory.
Default: "TRUE"
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"
The image options are:
Default: "TRUE"
Default: "4"
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"
The print options are:
Default: "Page &"
Default: "&w"
Default: "helv"
Default: "8"
Default: "&d &t"
Default: "&u"
You can use these special characters in the header and footer strings:
These options are for the Voyager server only. The SOCKS options are:
Default: none
Default: none
Default: none
Default: none
The TCP/IP options are:
Fill network buffers before processing them.
Default: "TRUE"
Default: "2400"
The disk-cache options are:
Default: "FALSE"
Default: "0"
Note: Verifying is done by using the “If-Modified-Since” request-header.
Default: "TRUE"
Keep the disk-cache index file updated on disk when it changes, instead of updating it once on exiting.
Default: "FALSE"
The directory used to store cache files.
Default: "/tmp"
Default: "5000"
The name of the cache index file.
Default: "main.ndx"
The miscellaneous options are:
Default: "e90e" (the insert cursor)
Default: "e90c" (the finger cursor)
Default: "e900" (the pointer cursor)
Default: "50"
Default: "TRUE"
Default: "TRUE"
Default: "4"
Voyager-server-only miscellaneous options:
Default: "TRUE"
Default: "TRUE"
Default: none
Default: "4"
Default: "1024"
Default: "e90c" (the finger cursor)
Default: "e900" (the pointer cursor)
Default: "e918" (the point-wait cursor)
Default: "e918" (the point-wait cursor)
Default: "4"
Default: "0"
Default: "FALSE"
Default: "500"
Default: "TRUE"
Default: "e908" (the wait cursor)
These options are specific to the netfront server.
These options are write-only:
Default: "TRUE"
Default: "DISABLES_NONE"
Set to "FLAG_NONE" to clear all flags.
Default: all flags enabled.
Set to "FLAG_NONE" for none.
Default: all flags enabled.
Default: "TRUE"
Default: "TRUE"
Default: "TRUE"
Default: "FALSE"
Default: "-1"
Default: "-1"
Default: "-1"
Default: "0"
Default: "0"
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"
Default: "FALSE"
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.
Default: "-1"
Default: "IMAGERESIZE_SIMPLE"
Default: "TRUE"
Default: "-1"
Default: "FALSE"
Default: "4"
Default: "20"
Default: "1500"
Default: "800"
Default: "-1"
Default: "60"
Default: "82"
Default: "100"
Default: "FALSE"
Default: "-1"
Default: "FALSE"
Default: "TRUE"
Default: "FALSE"
Default: "8"
Default: "TRUE"
Default: "TRUE"
Default: "FALSE"
Default: "2"
Default: "2"
Default: "TRUE"
Default: "TRUE"
Default: "FALSE"
Or: "FLAG_NONE" — none of the above.
Default: "FLAG_NONE"
Default: "FALSE"
Default: "FALSE"
Default: "TRUE"
Default: "TABORDER_DISPLAY"
Default: "1"
Default: "1"
Default: "1"
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. |
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. |
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. |
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. |
Default: "FALSE"
Default: "COOKIE_NOTIFY_BEFORE_SET"
Default: "4"
Default: "-1" (no limit)
Default: "-1" (no limit)
Default: "300"
Default: "20"
Default: "4096"
Default: "30"
Default: "-1" (no limit)
Default: "-1" (no limit)
Default: "TRUE"
Default: "TRUE"
Default: "TRUE"
Default: "FALSE"
Default: "TRUE"
Default: "30"
Default: "30"
Default: "19"
Default: "19"
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:
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. |
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);
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.
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.
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:
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.
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);
C type | Pt type | Default |
---|---|---|
PtWebClient2UnknownData_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; } PtWebClient2UnknownData_t;
The members include:
C type | Pt type | Default |
---|---|---|
char * | String |
Get the value of this resource to obtain the version of the connected web server.
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:
typedef struct { short type; short action; char *realm; char *url; } PtWebAuthenticateCallback_t;
The members of the PtWebAuthenticateCallback_t structure are:
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:
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:
typedef struct { char *url; } PtWebCompleteCallback_t;
The url member points to the URL of the page that has just completed.
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:
typedef struct { long context; PhPoint_t pos; } PtWebContextCallback_t;
The members of the PtWebContextCallback_t structure are:
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:
typedef struct { int type; int length; char *url; } PtWebDataReqCallback_t;
The members of the PtWebDataReqCallback_t structure are:
For an example of using the client protocol, see Pt_ARG_WEB_DATA.
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:
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:
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:
typedef struct { short type; short reason; char *url; char *description; } PtWebErrorCallback_t;
The members of the PtWebErrorCallback_t structure are:
If type is Pt_WEB_ERROR_WML, an error occurred in WML content, and the reason member contains one of:
For other values of type, the possible values of reason are:
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:
typedef struct { int reason; char *description; } PtWebImportCertificateCallback_t;
The reason is one of:
If reason is Pt_WEB_IMPORT_CERTIFICATE_ERROR, description is a textual explanation for the error.
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 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:
typedef struct { char *url; char *name; char *value; } PtWebMetaDataCallback_t;
The members include the following:
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 ); }
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:
typedef struct { short dir; } PtWebNeedScrollCallback_t;
where dir indicates the direction to scroll:
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:
typedef struct { PhDim_t size; long flags; } PtWebWindowCallback_t;
The members of the PtWebWindowCallback_t structure are:
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:
typedef struct { long vheight; long vwidth; long height; long width; long ypos; long xpos; } PtWebPageInfoCallback_t;
The members of the PtWebPageInfoCallback_t structure are:
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:
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:
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.
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:
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:
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:
When this callback is invoked, typically the client displays a dialog giving three choices to the user:
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:
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:
typedef struct { int ncert; char *url; int reserved1; int reserved2; PtWebSSLCertInfo_t *info; } PtWebSSLClientCertCallback_t;
The members of the PtWebSSLClientCertCallback_t structure include:
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:
typedef struct { short certerr; short trusted; char *url; int reason; } PtWebSSLErrorCallback_t;
The members of the PtWebSSLErrorCallback_t structure are:
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:
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:
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:
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:
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:
typedef struct { short action; short flags; char *content_type; int content_length; char *url; } PtWebUnknownCallback_t;
The members of the PtWebUnknownCallback_t structure are:
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:
typedef struct { char *url; } PtWebUrlCallback_t;
If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.
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.