adbus_Member Struct Reference

Handle to an idividual member in an adbus_Interface. More...

Related Functions
(Note that these are not member functions.)
void	adbus_mbr_argsig (adbus_Member *m, const char *sig, int size)
	Appends to the argument signature.
void	adbus_mbr_argname (adbus_Member *m, const char *name, int size)
	Sets the next argument name.
void	adbus_mbr_retsig (adbus_Member *m, const char *sig, int size)
	Appends to the return argument signature.
void	adbus_mbr_retname (adbus_Member *m, const char *name, int size)
	Sets the next return argument name.
void	adbus_mbr_annotate (adbus_Member *m, const char *name, int nameSize, const char *value, int valueSize)
	Adds an annotation to the member.
void	adbus_mbr_addrelease (adbus_Member *m, adbus_Callback release, void *ruser)
	Adds a callback and user data to be called when the interface is freed.
void	adbus_mbr_setmethod (adbus_Member *m, adbus_MsgCallback callback, void *user1)
	Sets the method callback.
void	adbus_mbr_setgetter (adbus_Member *m, adbus_MsgCallback callback, void *user1)
	Sets the get callback for properties.
void	adbus_mbr_setsetter (adbus_Member *m, adbus_MsgCallback callback, void *user1)
	Sets the set callback for properties.
int	adbus_mbr_call (adbus_Member *mbr, adbus_ConnBind *bind, adbus_CbData *d)
	Calls a method member directly.

---

Detailed Description

Handle to an idividual member in an adbus_Interface.

Note:

If writing C code, it's easiest to pull out arguments in callbacks via the adbus_check_* functions (eg adbus_check_boolean()).

Methods

Methods are added to the interface using adbus_iface_addmethod(). The caller can then set:

• Arguments via adbus_mbr_argsig() and adbus_mbr_argname().
• Return arguments via adbus_mbr_retsig() and adbus_mbr_retname().
• Annotations via adbus_mbr_annotate().
• Method callback via adbus_mbr_setmethod().

The caller must set a method callback.

When setting the method callback, you can also set a user data value which comes through to the callback as the adbus_CbData::user1 field. This way the same function can be reused for multiple methods.

User data can also be tied to the method so that it can be freed when the interface is eventually freed using adbus_mbr_addrelease().

For example:

  struct MultiplyData
  {
      int Multiplier;
  };

  static int Multiply(adbus_CbData* d)
  {
      int32_t num = adbus_check_i32(d);
      adbus_check_end(d);

      MultiplyData* mul = (MultiplyData*) d->user1;

      if (d->ret)
          adbus_msg_i32(d->ret, num * mul->Multiplier);

      return 0;
  }

  MultiplyData* multiply1 = (MultiplyData*) calloc(sizeof(MultiplyData), 1);
  MultiplyData* multiply2 = (MultiplyData*) calloc(sizeof(MultiplyData), 1);
  multiply1->Multiplier = 1;
  multiply2->Multiplier = 2;

  m = adbus_iface_addmethod(i, "Multiply1", -1);
  adbus_mbr_setmethod(m, &Multiply, multiply1);
  adbus_mbr_addrelease(m, &free, multiply1);
  adbus_mbr_argsig(m, "i", -1);
  adbus_mbr_retsig(m, "i", -1);

  m = adbus_iface_addmethod(i, "Multiply2", -1);
  adbus_mbr_setmethod(m, &Multiply, multiply2);
  adbus_mbr_addrelease(m, &free, multiply2);
  adbus_mbr_argsig(m, "i", -1);
  adbus_mbr_retsig(m, "i", -1);

The method callback can use the user2 field supplied in the bind (see adbus_Bind) to distinguish between the method being called on multiple objects.

For example:

  class Multiplier
  {
  public:
      Multiplier(int num) : m_Num(num) {}
  private:
      static int Multiply(adbus_CbData* d);
      static void Free(void* d) {delete (Multiplier*) d;}
      int m_Num;
  };

  int Multiplier::Multiply(adbus_CbData* d)
  {
      int num = adbus_check_i32(d);
      adbus_check_end(d);

      Multiplier* s = (Multiplier*) d->user2;
      if (d->ret)
          adbus_check_i32(d->ret, s->m_Num * num);

      return 0;
  }
  
  adbus_Interface* iface;
  adbus_Member* mbr;

  iface = adbus_iface_new("org.freedesktop.SampleInterface", -1);
  mbr = adbus_iface_addmethod(iface, "Multiply", -1);
  adbus_mbr_setmethod(mbr, &Multiplier::Multiply, NULL);
  adbus_mbr_argsig(mbr, "i", -1);
  adbus_mbr_retsig(mbr, "i", -1);

  Multiplier* mul3 = new Multiplier(3);

  adbus_Bind bind;
  adbus_bind_init(&bind);
  bind.interface  = iface;
  bind.path       = "/Mul3";
  bind.cuser2     = mul3;
  bind.release[0] = &Multiply::Free;
  bind.ruser[0]   = mul3;
  adbus_conn_bind(connection, &bind);

Signals

Signals are added to an interface using adbus_mbr_addsignal(). The caller can then set:

• Signal arguments via adbus_mbr_argsig() and adbus_mbr_argname().
• Annotations via adbus_mbr_annotate().

After binding the interface to a path, signals can be emitted by either manually building a signal message and sending or using the adbus_Signal utility module.

For example:

  // Create an interface with a single signal "Changed" which has a single
  // boolean argument
  adbus_Interface* iface;
  adbus_Member* mbr;
  iface = adbus_iface_new("org.freedesktop.SampleInterface", -1);
  mbr = adbus_iface_addsignal(iface, "Changed", -1);
  adbus_mbr_argsig(mbr, "b", -1);

  // Bind this interface to the path "/"
  adbus_Bind bind;
  adbus_bind_init(&bind);
  bind.interface = iface;
  bind.path      = "/";
  adbus_conn_bind(connection, &bind);

  // Create an adbus_Signal that we can use to emit the signal and bind it
  // to our changed signal at the path "/"
  adbus_Signal* sig = adbus_sig_new();
  adbus_sig_bind(sig, mbr, connection, "/", -1);

  // Emit our signal
  adbus_MsgFactory* msg = adbus_sig_msg(sig);
  adbus_msg_boolean(msg, 1);
  adbus_sig_emit(sig);

Properties

Properties are added to an interface using adbus_mbr_addproperty(). The caller can then set:

• Property get and set callbacks via adbus_mbr_setgetter() and adbus_mbr_setsetter().
• Annotations via adbus_mbr_annotate().

The access property exported through the introspection xml is determined by looking at which of the getter and setter callbacks are set.

Note:

One of adbus_mbr_setgetter(), adbus_mbr_setsetter(), or both must be called with a valid callback.

For example:

  adbus_Bool sFoo = 0;
  int SetFoo(adbus_CbData* d)
  { 
      return adbus_iter_boolean(d->setprop, &sFoo); 
  }

  int GetFoo(adbus_CbData* d)
  { 
      adbus_buf_boolean(d->getprop, sFoo);
      return 0;
  }

  // Create an interface with a single read/write boolean property "Foo"
  adbus_Interface* iface;
  adbus_Member* mbr;
  iface = adbus_iface_new("org.freedesktop.SampleInterface", -1);
  mbr = adbus_iface_addproperty(iface, "Foo", -1, "b", -1);
  adbus_mbr_setgetter(mbr, &SetFoo, NULL);
  adbus_mbr_setsetter(mbr, &GetFoo, NULL);

  int SetFoo(adbus_CbData* d)
  {
      sFoo = adbus_check_boolean(d);
      return 0;
  }

---

Friends And Related Function Documentation

void adbus_mbr_addrelease	(	adbus_Member *	m,
		adbus_Callback	release,
		void *	ruser
	)			[related]

Adds a callback and user data to be called when the interface is freed.

Warning:

The callback can be called on any thread.

void adbus_mbr_argname	(	adbus_Member *	m,
		const char *	name,
		int	size
	)			[related]

Sets the next argument name.

Arguments do not require a name and the name can be set before or after the signature is set, but there cannot be more argument names than argument signatures by the time this interface is bound.

Can only be called on method and signal members.

void adbus_mbr_argsig	(	adbus_Member *	m,
		const char *	sig,
		int	size
	)			[related]

Appends to the argument signature.

This merely appends to the full argument signature so multiple arguments can be added in one shot.

Can only be called on method and signal members.

int adbus_mbr_call	(	adbus_Member *	mbr,
		adbus_ConnBind *	bind,
		adbus_CbData *	d
	)			[related]

Calls a method member directly.

Note:

This may proxy the method call to another thread.

This is useful when using the dbus binding for other purposes eg bindings into an embedded scripting language.

The bind can be gotten from the return value of adbus_conn_bind() or by looking it up via adbus_conn_interface().

void adbus_mbr_retname	(	adbus_Member *	m,
		const char *	name,
		int	size
	)			[related]

Sets the next return argument name.

Arguments do not require a name and the name can be set before or after the signature is set, but there cannot be more argument names than argument signatures by the time this interface is bound.

Can only be called on method members.

void adbus_mbr_retsig	(	adbus_Member *	m,
		const char *	sig,
		int	size
	)			[related]

Appends to the return argument signature.

This merely appends to the full argument signature so multiple arguments can be added in one shot.

Can only be called on method members.

void adbus_mbr_setgetter	(	adbus_Member *	m,
		adbus_MsgCallback	callback,
		void *	user1
	)			[related]

Sets the get callback for properties.

At least one of this or adbus_mbr_setsetter() must be called befor ethe interface is bound.

Can only be called on property members.

void adbus_mbr_setmethod	(	adbus_Member *	m,
		adbus_MsgCallback	callback,
		void *	user1
	)			[related]

Sets the method callback.

This must be set before the interface is bound.

Can only be called on method members.

void adbus_mbr_setsetter	(	adbus_Member *	m,
		adbus_MsgCallback	callback,
		void *	user1
	)			[related]

Sets the set callback for properties.

At least one of this or adbus_mbr_setsetter() must be called befor ethe interface is bound.

Can only be called on property members.

---

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

• adbus/interface.c