PtClient
![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
PtClient
Client widget
Class hierarchy:
PtWidget --> PtBasic --> PtContainer --> PtClient
Immediate subclasses:
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:
| Resource | C type | Pt type | Default |
|---|---|---|---|
| Pt_ARG_CLIENT_FLAGS | unsigned | Flags | 0 |
| Pt_ARG_CLIENT_NAME | char * | String | NULL |
| Pt_ARG_CLIENT_REPLY_LEN | unsigned | Scalar | 0 |
| Pt_ARG_CLIENT_SEND | char, unsigned | Array | NULL, 0 |
| Pt_ARG_CLIENT_SERVER | PtConnectionClient_t * | Pointer | NULL |
| Pt_CB_CLIENT_CONNECTED | PtCallback_t * | Link | NULL |
| Pt_CB_CLIENT_ERROR | PtCallback_t * | Link | NULL |
| Pt_CB_CLIENT_EVENT | PtCallback_t * | Link | NULL |
| Pt_CB_CLIENT_NOT_FOUND | PtCallback_t * | Link | NULL |
Pt_ARG_CLIENT_FLAGS
| C type | Pt type | Default |
|---|---|---|
| unsigned | Flags | 0 |
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
| C type | Pt type | Default |
|---|---|---|
| char * | String | NULL |
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
| C type | Pt type | Default |
|---|---|---|
| unsigned | Scalar | 0 |
The maximum length of a reply from the server, in bytes. See Pt_ARG_CLIENT_SEND.
Pt_ARG_CLIENT_SEND
| C type | Pt type | Default |
|---|---|---|
| char, unsigned | Array | NULL, 0 |
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)
| C type | Pt type | Default |
|---|---|---|
| PtConnectionClient_t * | Pointer | NULL |
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
| C type | Pt type | Default |
|---|---|---|
| PtCallback_t * | Link | NULL |
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
| 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_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.
- 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.
These callbacks should return Pt_CONTINUE.
Pt_CB_CLIENT_EVENT
| C type | Pt type | Default |
|---|---|---|
| PtCallback_t * | Link | NULL |
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
| C type | Pt type | Default |
|---|---|---|
| PtCallback_t * | Link | NULL |
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.
|
|
|
|