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.

---

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:

Pt_ARG_SERVER_CONNECTION

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

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)

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

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

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.

  ---

  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.

  ---

  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

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

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.