This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PtClient

Client widget

Class hierarchy:

PtWidget → PtBasic → PtContainer → PtClient

Immediate subclasses:

• PtWebClient

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

PhAB icon:

None — not normally instantiated.

Public header:

<photon/PtClient.h>

Description:

PtClient and PtServer let one process (the “server”) display widgets in a window that belongs to another process (the “client”).

PtClient and PtServer use a Photon connection to communicate (see “Connections” in the Interprocess Communications chapter of the Photon Programmer's Guide), but they have a few resources that in most cases let applications avoid dealing with connection objects directly.

A PtClient widget creates a parent region for a PtServer widget and handles the process of connecting to a PtServer. Then, the client controls the server's size and notifies it of certain events in order to make the server look and feel as if it were just another container in the client's window. Additionally, PtClient lets your application send arbitrary messages to the server process.

New resources:

Pt_ARG_CLIENT_FLAGS

Flags that control the behavior of the widget:

Pt_CLIENT_NOEVENTS

Setting this flag tells the widget that the server doesn't use the Pt_ARG_SERVER_SEND resource.

Pt_CLIENT_NONBLOCK

If this flag is clear, the call to PtSetResources() that sets Pt_ARG_CLIENT_NAME doesn't return until the connecting has either succeeded or been aborted.

If the flag is set, setting the Pt_ARG_CLIENT_NAME is nonblocking, and the connecting is performed in background, after PtSetResources() has returned.

Pt_ARG_CLIENT_NAME

The connector name to which to connect. Setting this resource initiates the process of connecting to a server.

If the connection isn't successful, the widget's Pt_CB_CLIENT_NOT_FOUND callbacks are invoked.

Pt_ARG_CLIENT_REPLY_LEN

The maximum length of a reply from the server, in bytes. See Pt_ARG_CLIENT_SEND.

Pt_ARG_CLIENT_SEND

When you set this resource, the widget sends a message to its PtServer. The message invokes a Pt_CB_SERVER_RECEIVE callback in the server that lets the server specify a reply. The reply is then available in the client by getting the Pt_ARG_CLIENT_SEND resource (the length gives you the actual length of the reply, not the size of the buffer).

Pt_ARG_CLIENT_SERVER (read only)

A pointer to the connection object used for communicating to the PtServer. Don't use this pointer for anything other than checking to see if it's NULL.

Pt_CB_CLIENT_CONNECTED

A list of PtCallback_t structures that define the callbacks that are invoked when the client connects to the server. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_CLIENT_CONNECTED

reason_subtype

0 (not used).

event

NULL.

cbdata

NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_CLIENT_ERROR

A list of PtCallback_t structures that define the callbacks that are invoked when an error occurs.

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

reason

Pt_CB_CLIENT_ERROR

reason_subtype

0 (not used).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.

cbdata

A pointer to a PtClientErrorCallback_t structure that contains at least:

• int action — the value that the connection client's error handler will return. It's initialized to Pt_END. Set it to Pt_CONTINUE to retry the failed operation.

  ---

  Not all operations are retried if an error handler returns Pt_CONTINUE. For example, a MsgReply() is never retried.

  ---

  
  
• int errnum — the errno value from the error handler.
• int where — the value (of type enum PtConnectionClientError) that describes what operation failed.

  ---

  If this value is Pt_CONNECTION_CLIENT_BROKEN, the widget disconnected from the server and its Pt_ARG_CLIENT_NAME resource has been reset to NULL.

  ---

These callbacks should return Pt_CONTINUE.

Pt_CB_CLIENT_EVENT

A list of PtCallback_t structures that define the callbacks that are invoked for each message sent by the server's Pt_ARG_SERVER_SEND resource.

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

reason

Pt_CB_CLIENT_EVENT

reason_subtype

0 (not used).

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.

cbdata

A pointer to a PtClientCallback_t structure that contains at least:

• void const *message — a pointer to the message.
• unsigned nbytes — its length.

These callbacks should return Pt_CONTINUE.

Pt_CB_CLIENT_NOT_FOUND

A list of PtCallback_t structures that define the callbacks that are invoked if the widget fails to find the server specified when you set Pt_ARG_CLIENT_NAME.

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

reason

Pt_CB_CLIENT_NOT_FOUND

reason_subtype

0 (not used).

event

NULL.

cbdata

A pointer to an int initialized to Pt_END. Set it to Pt_CONTINUE if you want the widget to retry after a little while. Typically, the first Pt_CB_CLIENT_NOT_FOUND callback spawns the server, and any subsequent Pt_CB_CLIENT_NOT_FOUND callback checks whether or not the server is still running, and abort the connecting if the server has terminated.

These callbacks should return Pt_CONTINUE.

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.