adbus_Proxy Struct Reference

Helper class to access members of a specific remote object. More...

Related Functions
(Note that these are not member functions.)
adbus_Proxy *	adbus_proxy_new (adbus_State *state)
	Create a new proxy tied to the provided state.
void	adbus_proxy_free (adbus_Proxy *p)
	Frees the proxy.
void	adbus_proxy_init (adbus_Proxy *p, adbus_Connection *connection, const char *service, int ssize, const char *path, int psize)
	Reset and reinitialise the proxy.
void	adbus_proxy_setinterface (adbus_Proxy *p, const char *interface, int isize)
	Set the proxy interface.
void	adbus_proxy_signal (adbus_Proxy *p, adbus_Match *m, const char *signal, int size)
	Add a signal match.
void	adbus_call_method (adbus_Proxy *p, adbus_Call *call, const char *method, int size)
	Setup an adbus_Call structure for a method call.
void	adbus_call_setproperty (adbus_Proxy *p, adbus_Call *call, const char *property, int propsize, const char *type, int typesize)
	Setup an adbus_Call structure to set a property.
void	adbus_call_getproperty (adbus_Proxy *p, adbus_Call *call, const char *property, int size)
	Setup an adbus_Call structure to get a property.
void	adbus_call_send (adbus_Proxy *p, adbus_Call *call)
	Send off a call.

---

Detailed Description

Helper class to access members of a specific remote object.

adbus_Proxy acts as a simple wrapper around a specific remote object to ease calling methods, setting/getting properties, and adding matches for signals on that object.

All callbacks are registered with a provided adbus_State and their lifetime is tied to the state not the proxy. This means that the proxy can be modified, freed, reset, etc without losing the original callbacks.

The user can optionally set the interface, but this is required for accessing properties and signals.

Warning:

Only one adbus_Call can be active at a time.

The proxy can only be used from the creating thread and must be on the same thread as the associated state.

Methods

Method calling uses a helper class adbus_Call. The general workflow is:

1. Create an adbus_Call on the stack.
2. Call adbus_call_method() to setup the fields in the adbus_Call.
3. Setup arguments and callbacks in the adbus_Call fields.
4. Call adbus_call_send() to send off the message and register for any callbacks.

For example:

  struct my_state
  {
      adbus_State* state;
      adbus_Proxy* proxy;
  };

  struct my_state* CreateMyState(adbus_Connection* c)
  {
      struct my_state* ret = (struct my_state*) calloc(sizeof(struct my_state), 1);
      ret->state = adbus_state_new();
      ret->proxy = adbus_proxy_new(ret->state);

      adbus_proxy_init(ret->proxy, c, "com.example.ExampleService", -1, "/", -1);

      // This is required for properties and signals, but not calling methods.
      adbus_proxy_setinterface(ret->proxy, "com.example.ExampleInterface", -1);

      return ret;
  }

  void DeleteMyState(struct my_state* s)
  {
      if (s) {
          adbus_proxy_free(s->proxy);
          adbus_state_free(s->state);
          free(s);
      }
  }

  int Reply(adbus_CbData* d)
  {
      struct my_state* s = (struct my_state*) d->user1;
      // Do something
      return 0;
  }

  void CallMethod(struct my_state* s)
  {
      adbus_Call call;

      // Setup the call
      adbus_proxy_method(s->proxy, "ExampleMethod", -1);

      // Append some arguments
      adbus_msg_setsig(call.msg, "b", -1);
      adbus_msg_bool(call.msg, 1);

      // Setup callbacks
      call.callback = &Reply;
      call.cuser = s;

      // Send off the call
      adbus_call_send(s->proxy, &call);
  }

Properties

Note:

This requires that the interface be set with adbus_proxy_setinterface().

The workflow for getting/setting properties is very similar to calling methods:

1. Create an adbus_Call on the stack
2. Call adbus_call_setproperty() and adbus_call_getproperty() to setup the adbus_Call.
3. Append the property to adbus_Call::msg for adbus_call_setproperty(). Add callbacks for adbus_call_getproperty().
4. Send off the call using adbus_call_send().

Note:

When appending the property to the message you should not set the argument signature.

For example:

  void SetProperty(struct my_state* s)
  {
      adbus_Call call;

      // Setup the call
      adbus_proxy_setproperty(s->proxy, &call, "BooleanProperty", -1, "b", -1);

      // Append the argument
      adbus_msg_bool(call.msg, 1);

      // Send off the call
      adbus_call_send(s->proxy, &call);
  }

  void GetProperty(struct my_state* s)
  {
      adbus_Call call;

      // Setup the call
      adbus_proxy_getproperty(s->proxy, &call, "BooleanProperty", -1);

      // Set the callback
      call.callback = &Reply;
      call.cuser = s;

      // Send off the call
      adbus_call_send(s->proxy, &call);
  }

Signals

Note:

This requires that the interface be set with adbus_proxy_setinterface().

The proxy can also add signal matches through to the state for this remote object.

The workflow is:

1. Create a match on the stack and initialise it using adbus_match_init().
2. Set the callback in the match
3. Call adbus_proxy_signal() which will setup the remaining items and add it to the state.

For example:

  int OnSignal(adbus_CbData* d)
  {
      struct my_state* s = (struct my_state*) d->user1;
      // Do something
      return 0;
  }
  void AddSignalMatch(struct my_state* s)
  {
      adbus_Match m;
      adbus_match_init(&m);
      m.callback  = &OnSignal;
      m.cuser     = s;
      adbus_proxy_signal(s->proxy, &m, "ExampleSignal", -1);
  }

See also:

adbus_State

---

The documentation for this struct was generated from the following file:

• adbus/proxy.c