External plug/socket infrastructure for remote canvases

Functions | Variables
External plug/socket infrastructure for remote canvases
Ecore » Ecore_Evas wrapper/helper set of functions

These functions allow 1 process to create a "socket" was pluged into which another process can create a "plug" remotely to plug into. More...

## Functions
EAPI Ecore_Evas * | ecore_evas_extn_socket_new (int w, int h)
| Creates a new Ecore_Evas canvas for the new external ecore evas socket. More...
EAPI Eina_Bool | ecore_evas_extn_socket_listen (Ecore_Evas *ee, const char *svcname, int svcnum, Eina_Bool svcsys)
| Creates a socket to provide the service for external ecore evas socket. More...
EAPI void | ecore_evas_extn_socket_events_block_set (Ecore_Evas *ee, Eina_Bool events_block)
| Sets the blocking about mouse events to Ecore Evas. More...
EAPI Eina_Bool | ecore_evas_extn_socket_events_block_get (Ecore_Evas *ee)
| Gets the blocking about mouse events to Ecore Evas. More...
EAPI void | ecore_evas_extn_plug_object_data_lock (Evas_Object *obj)
| Locks the pixel data so the socket cannot change it. More...
EAPI void | ecore_evas_extn_plug_object_data_unlock (Evas_Object *obj)
| Unlocks the pixel data so the socket can change it again. More...
EAPI Evas_Object * | ecore_evas_extn_plug_new (Ecore_Evas *ee_target)
| Creates a new external ecore evas plug. More...
EAPI Eina_Bool | ecore_evas_extn_plug_connect (Evas_Object *obj, const char *svcname, int svcnum, Eina_Bool svcsys)
| Connects an external ecore evas plug to service provided by external ecore evas socket. More...

## Variables
EAPI int | ECORE_EVAS_EXTN_CLIENT_ADD
| this event is received when a plug has connected to an extn socket More...
EAPI int | ECORE_EVAS_EXTN_CLIENT_DEL
| this event is received when a plug has disconnected from an extn socket More...

## Detailed Description

These functions allow 1 process to create a "socket" was pluged into which another process can create a "plug" remotely to plug into.

Socket can provide content for several plugs. This is best for small sized objects (about the size range of a small icon up to a few large icons). Since the plug is actually an image object, you can fetch the pixel data

Since
  1.2

## Function Documentation

## ◆ ecore_evas_extn_socket_new()

EAPI Ecore_Evas* ecore_evas_extn_socket_new | ( | int | w,
|  | int | h
| ) |  |

Creates a new Ecore_Evas canvas for the new external ecore evas socket.

Parameters

  w | The width of the canvas, in pixels
  h | The height of the canvas, in pixels

Returns
  A new `Ecore_Evas` instance, or `NULL` on failure

This creates a new extn_socket canvas wrapper, with image data array bound to the ARGB format, 8 bits per pixel.

If creation is successful, an Ecore_Evas handle is returned or `NULL` if creation fails. Also focus, show, hide etc. callbacks will also be called if the plug object is shown, or already visible on connect, or if it is hidden later, focused or unfocused.

This function has to be followed by ecore_evas_extn_socket_listen(), for starting ecore ipc service.

Eina_Bool res = EINA_FALSE;
Ecore_Evas *ee = ecore_evas_extn_socket_new(1, 1);
res = ecore_evas_extn_socket_listen("svcname", 1, EINA_FALSE);
if (!res) return;
ecore_evas_resize(ee, 240, 400);
ecore_evas_extn_socket_new
EAPI Ecore_Evas * ecore_evas_extn_socket_new(int w, int h)
Creates a new Ecore_Evas canvas for the new external ecore evas socket.
Definition: ecore_evas.c:4263
ecore_evas_extn_socket_listen
EAPI Eina_Bool ecore_evas_extn_socket_listen(Ecore_Evas *ee, const char *svcname, int svcnum, Eina_Bool svcsys)
Creates a socket to provide the service for external ecore evas socket.
Definition: ecore_evas.c:4284
ecore_evas_resize
EAPI void ecore_evas_resize(Ecore_Evas *ee, int w, int h)
Resizes an Ecore_Evas.
Definition: ecore_evas.c:1324
EINA_FALSE
#define EINA_FALSE
boolean value FALSE (numerical value 0)
Definition: eina_types.h:533
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition: eina_types.h:527

or

Eina_Bool res = EINA_FALSE;
Ecore_Evas *ee = ecore_evas_extn_socket_new(240, 400);
res = ecore_evas_extn_socket_listen("svcname", 1, EINA_FALSE);
if (!res) return;

When a client(plug) connects, you will get the ECORE_EVAS_EXTN_CLIENT_ADD event in the ecore event queue, with event_info being the image object pointer passed as a void pointer. When a client disconnects you will get the ECORE_EVAS_EXTN_CLIENT_DEL event.

You can set up event handles for these events as follows:

static Eina_Bool client_add_cb(void *data, int event, void *event_info)
{
Ecore_Evas *ee = event_info;
printf("client is connected to external socket %p\n", ee);
return ECORE_CALLBACK_PASS_ON;
}
static Eina_Bool client_del_cb(void *data, int event, void *event_info)
{
Ecore_Evas *ee = event_info;
printf("client is disconnected from external socket %p\n", ee);
return ECORE_CALLBACK_PASS_ON;
}
void setup(void)
{
ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_ADD,
client_add_cb, NULL);
ecore_event_handler_add(ECORE_EVAS_EXTN_CLIENT_DEL,
client_del_cb, NULL);
}
ECORE_EVAS_EXTN_CLIENT_ADD
EAPI int ECORE_EVAS_EXTN_CLIENT_ADD
this event is received when a plug has connected to an extn socket
Definition: ecore_evas_extn.c:8
ECORE_EVAS_EXTN_CLIENT_DEL
EAPI int ECORE_EVAS_EXTN_CLIENT_DEL
this event is received when a plug has disconnected from an extn socket
Definition: ecore_evas_extn.c:9
ecore_event_handler_add
Ecore_Event_Handler * ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data)
Adds an event handler.
Definition: ecore_events.c:13
ECORE_CALLBACK_PASS_ON
#define ECORE_CALLBACK_PASS_ON
Return value to pass event to next handler.
Definition: Ecore_Common.h:155

Note that events come in later after the event happened. You may want to be careful as data structures you had associated with the image object may have been freed after deletion, but the object may still be around awaiting cleanup and thus still be valid.You can change the size with something like:

See also
  ecore_evas_extn_socket_listen()
  ecore_evas_extn_plug_new()
  ecore_evas_extn_plug_object_data_lock()
  ecore_evas_extn_plug_object_data_unlock()

Since
  1.2

References ecore_evas_free(), eina_module_symbol_get(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

## ◆ ecore_evas_extn_socket_listen()

EAPI Eina_Bool ecore_evas_extn_socket_listen | ( | Ecore_Evas * | ee,
|  | const char * | svcname,
|  | int | svcnum,
|  | Eina_Bool | svcsys
| ) |  |

Creates a socket to provide the service for external ecore evas socket.

Parameters

  ee | The Ecore_Evas.
  svcname | The name of the service to be advertised. ensure that it is unique (when combined with `svcnum`) otherwise creation may fail.
  svcnum | A number (any value, `0` being the common default) to differentiate multiple instances of services with the same name.
  svcsys | A boolean that if true, specifies to create a system-wide service all users can connect to, otherwise the service is private to the user ide that created the service.

Returns
  `EINA_TRUE` if creation is successful, `EINA_FALSE` if it does not.

This creates socket specified by `svcname`, `svcnum` and `svcsys`. If creation is successful, `EINA_TRUE` is returned or `EINA_FALSE` if creation fails.

See also
  ecore_evas_extn_socket_new()
  ecore_evas_extn_plug_new()
  ecore_evas_extn_plug_object_data_lock()
  ecore_evas_extn_plug_object_data_unlock()

Since
  1.2

References EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## ◆ ecore_evas_extn_socket_events_block_set()

EAPI void ecore_evas_extn_socket_events_block_set | ( | Ecore_Evas * | ee,
|  | Eina_Bool | events_block
| ) |  |

Sets the blocking about mouse events to Ecore Evas.

Parameters

  ee | The Ecore_Evas.
  events_block | The blocking about mouse events.

See also
  ecore_evas_extn_socket_events_block_get()

Since
  1.15

References eina_module_symbol_get(), and EINA_SAFETY_ON_NULL_RETURN.

## ◆ ecore_evas_extn_socket_events_block_get()

EAPI Eina_Bool ecore_evas_extn_socket_events_block_get | ( | Ecore_Evas * | ee | ) |

Gets the blocking about mouse events to Ecore Evas.

Parameters

  ee | The Ecore_Evas.

Returns
  The blocking about mouse events.

See also
  ecore_evas_extn_socket_events_block_set()

Since
  1.15

References EINA_FALSE, eina_module_symbol_get(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

## ◆ ecore_evas_extn_plug_object_data_lock()

EAPI void ecore_evas_extn_plug_object_data_lock | ( | Evas_Object * | obj | ) |

Locks the pixel data so the socket cannot change it.

Parameters

  obj | The image object returned by ecore_evas_extn_plug_new() to lock

You may need to get the image pixel data with evas_object_image_data_get() from the image object, but need to ensure that it does not change while you are using the data. This function lets you set an advisory lock on the image data so the external plug process will not render to it or alter it.

You should only hold the lock for just as long as you need to read out the image data or otherwise deal with it, and then unlock it with ecore_evas_extn_plug_object_data_unlock(). Keeping a lock over more than 1 iteration of the main ecore loop will be problematic, so avoid it. Also forgetting to unlock may cause the socket process to freeze and thus create odd behaviors.

See also
  ecore_evas_extn_plug_new()
  ecore_evas_extn_plug_object_data_unlock()

Since
  1.2

References ecore_evas_object_ecore_evas_get(), and EINA_SAFETY_ON_NULL_RETURN.

## ◆ ecore_evas_extn_plug_object_data_unlock()

EAPI void ecore_evas_extn_plug_object_data_unlock | ( | Evas_Object * | obj | ) |

Unlocks the pixel data so the socket can change it again.

Parameters

  obj | The image object returned by ecore_evas_extn_plug_new() to unlock

This unlocks after an advisor lock has been taken by ecore_evas_extn_plug_object_data_lock().

See also
  ecore_evas_extn_plug_new()
  ecore_evas_extn_plug_object_data_lock()

Since
  1.2

References ecore_evas_object_ecore_evas_get(), and EINA_SAFETY_ON_NULL_RETURN.

## ◆ ecore_evas_extn_plug_new()

EAPI Evas_Object* ecore_evas_extn_plug_new | ( | Ecore_Evas * | ee_target | ) |

Creates a new external ecore evas plug.

Parameters

  ee_target | The Ecore_Evas containing the canvas in which the new image object will live.

Returns
  An evas image object that will contain the image output of a socket.

This creates an image object that will contain the output of another processes socket canvas when it connects. All input will be sent back to this process as well, effectively swallowing or placing the socket process in the canvas of the plug process in place of the image object. The image object by default is created to be filled (equivalent of evas_object_image_filled_add() on creation) so image content will scale to fill the image unless otherwise reconfigured. The Ecore_Evas size of the plug is the master size and determines size in pixels of the plug canvas. You can change the size with something like:

Eina_Bool res = EINA_FALSE;
Evas_Object *obj = ecore_evas_extn_plug_new(ee);
res = ecore_evas_extn_plug_connect("svcname", 1, EINA_FALSE);
if (!res) return;
ecore_evas_resize(ee, 240, 400);
ecore_evas_extn_plug_connect
EAPI Eina_Bool ecore_evas_extn_plug_connect(Evas_Object *obj, const char *svcname, int svcnum, Eina_Bool svcsys)
Connects an external ecore evas plug to service provided by external ecore evas socket.
Definition: ecore_evas.c:4365
ecore_evas_extn_plug_new
EAPI Evas_Object * ecore_evas_extn_plug_new(Ecore_Evas *ee_target)
Creates a new external ecore evas plug.
Definition: ecore_evas.c:4352
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition: Evas_Common.h:185

See also
  ecore_evas_extn_socket_new()
  ecore_evas_extn_plug_connect()

Since
  1.2

References eina_module_symbol_get(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

## ◆ ecore_evas_extn_plug_connect()

EAPI Eina_Bool ecore_evas_extn_plug_connect | ( | Evas_Object * | obj,
|  | const char * | svcname,
|  | int | svcnum,
|  | Eina_Bool | svcsys
| ) |  |

Connects an external ecore evas plug to service provided by external ecore evas socket.

Parameters

  obj | The Ecore_Evas containing the canvas in which the new image object will live.
  svcname | The service name to connect to set up by the socket.
  svcnum | The service number to connect to (set up by socket).
  svcsys | Boolean to set if the service is a system one or not (set up by socket).

Returns
  `EINA_TRUE` if creation is successful, `EINA_FALSE` if it does not.

See also
  ecore_evas_extn_plug_new()

Since
  1.2

References ecore_evas_object_ecore_evas_get(), EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## Variable Documentation

## ◆ ECORE_EVAS_EXTN_CLIENT_ADD

EAPI int ECORE_EVAS_EXTN_CLIENT_ADD
| extern

this event is received when a plug has connected to an extn socket

Since
  1.2

## ◆ ECORE_EVAS_EXTN_CLIENT_DEL

EAPI int ECORE_EVAS_EXTN_CLIENT_DEL
| extern

this event is received when a plug has disconnected from an extn socket

Since
  1.2