PtServer

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

PtServer

Server widget

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtRegion --> PtServer

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

PhAB icon:

None -- instantiate it by calling PtCreateWidget().

Public header:

<photon/PtServer.h>

Description:

PtClient and PtServer allow one process (the "server") to 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 PtServer widget displays its contents inside the PtClient it's attached to. The contents can be any widgets you choose to put in your PtServer widget. Additionally, PtServer lets your application send arbitrary messages to the client process.

When a PtServer is attached to a PtClient, it's the client that decides what size your server should be and when it should be realized, unrealized, and destroyed.


Note: Don't try to resize, realize, unrealize, or destroy a PtServer widget that's connected to a client. Don't exit from an application that has active PtServer widgets. If you need to do any of those things, you should do it by sending a message to ask the client to do the appropriate action on its PtClient widget instead.

New resources:

Resource C type Pt type Default
Pt_ARG_SERVER_CONNECTION PtConnectionServer_t * Pointer NULL
Pt_ARG_SERVER_NAME char * String NULL
Pt_ARG_SERVER_SEND char, int Array (write only)
Pt_CB_SERVER_CONNECTED PtCallback_t * Link NULL
Pt_CB_SERVER_ERROR PtCallback_t * Link NULL
Pt_CB_SERVER_RECEIVE PtCallback_t * Link NULL
Pt_CB_SERVER_TRANSPORT PtCallback_t * Link NULL

Pt_ARG_SERVER_CONNECTION

C type Pt type Default
PtConnectionServer_t * Pointer NULL

A pointer to the connection object used for communicating to the PtClient. If you get the value of this resource, don't use this pointer for anything other than checking to see if it's NULL.

You can set this resource, provided that the widget isn't connected to a client yet. This is useful in a server application that has a connector that multiple clients can connect to. This kind of server has a connector callback that creates a PtServer widget and gives the new connection object to its Pt_ARG_SERVER_CONNECTION resource (see PtConnectorCreate() in the Photon Library Reference for more details about connectors).

In a server that just creates one PtServer widget, the Pt_ARG_SERVER_NAME resource is a simpler way of connecting to a client.

Pt_ARG_SERVER_NAME

C type Pt type Default
char * String NULL

When you set this resource, the widget creates a connector and lets a client connect to it. After the client has connected, the connector is automatically destroyed.

Pt_ARG_SERVER_SEND (write only)

C type Pt type Default
char, int Array

When you set this resource, the widget sends the given message to the client PtClient that invokes the Pt_CB_CLIENT_EVENT callback.

Pt_CB_SERVER_CONNECTED

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks invoked when a client connects to the widget.

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

reason
Pt_CB_SERVER_CONNECTED
reason_subtype
0 (not used).
event
NULL (not used).
cbdata
NULL.

These callbacks should return Pt_CONTINUE.

Pt_CB_SERVER_ERROR

C type Pt type Default
PtCallback_t * Link NULL

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_SERVER_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 PtServerErrorCallback_t structure that contains at least:
  • int action -- the value that the PtConnectionServer error handler will return. It's initialized to Pt_END. Set it to Pt_CONTINUE to retry the failed operation.

    Note: 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 PtConnectionServerError) that describes what operation failed.

    Note: If this value is Pt_CONNECTION_SERVER_BROKEN, the widget is destroyed after the callback returns.

These callbacks should return Pt_CONTINUE.

Pt_CB_SERVER_RECEIVE

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that are invoked when the server receives a message sent by the client's Pt_ARG_CLIENT_SEND resource.

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

reason
Pt_CB_SERVER_RECEIVE
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 PtServerCallback_t structure that contains at least:
  • void const *message -- the message from the client.
  • unsigned msg_len -- its length, in bytes.
  • void *reply -- set this to point to your reply buffer.
  • unsigned reply_len -- put its length here.

These callbacks should return Pt_CONTINUE.

Pt_CB_SERVER_TRANSPORT

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks that are invoked when the PtClient that the PtServer is attached to is realized in a Photon session different from the one that the server is connected to. This can happen when the client is being transported to a different Photon.

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

reason
Pt_CB_SERVER_TRANSPORT
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 the pathname of the new Photon device.

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.

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtWidget Not used by this class.
Pt_ARG_ANCHOR_OFFSETS PtWidget Not used by this class.
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget 0
Pt_ARG_BITMAP_CURSOR PtWidget
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_LAYOUT_INFO PtContainer
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_GRID_LAYOUT_INFO PtContainer
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LAYOUT PtContainer
Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_LAYOUT_INFO PtContainer
Pt_ARG_LAYOUT_TYPE PtContainer
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_REGION_FIELDS PtRegion 0x00000018
Pt_ARG_REGION_FLAGS PtRegion
Pt_ARG_REGION_INFRONT PtRegion
Pt_ARG_REGION_INPUT_GROUP PtRegion
Pt_ARG_REGION_OPAQUE PtRegion 0x00210EF8
Pt_ARG_REGION_PARENT PtRegion
Pt_ARG_REGION_SENSE PtRegion 0x00290240
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_ARG_ROW_LAYOUT_INFO PtContainer
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_CHILD_GETTING_FOCUS PtContainer
Pt_CB_CHILD_LOSING_FOCUS PtContainer
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_LAYOUT PtContainer
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