adbus_Reply Struct Reference

Data structure to register for return and error messages from a method call. More...

Data Fields
uint32_t	serial
	The serial that replies and errors will be sent in response to.
const char *	remote
	The remote the original method call was sent to.
int	remoteSize
	Length of the adbus_Reply::remote field or -1 if null terminated (default).
adbus_MsgCallback	callback
	Function to call on a reply message.
void *	cuser
	User data for the adbus_Reply::callback field.
adbus_MsgCallback	error
	Function to call on an error reply.
void *	euser
	User data for the adbus_Reply::error field.
adbus_ProxyMsgCallback	proxy
	Proxy function to use to call the callback and error fields.
void *	puser
	User data for the adbus_Reply::proxy field.
adbus_Callback	release [2]
	Function to call when the reply is removed.
void *	ruser [2]
	User data for the adbus_Reply::release field.
adbus_ProxyCallback	relproxy
	Proxy funciton to use to call the release fields.
void *	relpuser
	User data for the adbus_Reply::relproxy field.
Related Functions
(Note that these are not member functions.)
void	adbus_reply_init (adbus_Reply *r)
	Initialise an adbus_Reply structure.

---

Detailed Description

Data structure to register for return and error messages from a method call.

Note:

An adbus_Reply structure should always be initialised using adbus_reply_init().

The proxy and relproxy fields should almost always be initialised using adbus_conn_getproxy().

The normal procedure to call method including registering for its reply is:

1. Get a serial for the method call.

1. Register for the reply by setting up an adbus_Reply and calling adbus_conn_addreply() or adbus_state_addreply() to register.

1. Send the method call using adbus_conn_send() or adbus_msg_send().

For example:

  static int Reply(adbus_CbData* d)
  {
      Object* o = (Object*) d->user1;
      o->OnReply();
      return 0;
  }

  static int Error(adbus_CbData* d)
  {
      Object* o = (Object*) d->user1;
      o->OnError();
      return 0;
  }

  void CallMethod(adbus_Connection* c, Object* o)
  {
      uint32_t serial = adbus_conn_serial(c);

      // Register for the reply
      adbus_Reply reply;
      adbus_reply_init(&reply);
      reply.serial = serial;
      reply.remote = "com.example.Service";
      reply.user   = o;
      adbus_state_addreply(o->state(), c, &reply);

      // Setup the method call
      adbus_MsgFactory* m = adbus_msg_new();
      adbus_msg_settype(m, ADBUS_MSG_METHOD);
      adbus_msg_setserial(m, serial);
      adbus_msg_setdestination(m, "com.example.Service", -1); 
      adbus_msg_setpath(m, "/", -1);
      adbus_msg_setmember(m, "ExampleMethod");

      // Send the method call
      adbus_msg_send(m, c);
      adbus_msg_free(m);
  }

Note:

If writing C code, the adbus_State and adbus_Proxy modules vastly simplify the unregistering and thread jumping issues.

Warning:

If using adbus_conn_addreply() directly you should use a release callback to figure out if its safe to call adbus_conn_removereply, since replies are automatically removed upon receiving the first error or reply message.

See also:

adbus_Connection, adbus_conn_addreply(), adbus_state_addreply(), adbus_Proxy

---

Field Documentation

adbus_Reply::proxy

Proxy function to use to call the callback and error fields.

Normally this should be set using adbus_conn_getproxy().

adbus_Reply::puser

User data for the adbus_Reply::proxy field.

Normally this should be set using adbus_conn_getproxy().

adbus_Reply::relproxy

Proxy funciton to use to call the release fields.

Normally this should be set using adbus_conn_getproxy().

adbus_Reply::relpuser

User data for the adbus_Reply::relproxy field.

Normally this should be set using adbus_conn_getproxy().

adbus_Reply::remote

The remote the original method call was sent to.

Strictly speaking this is not required as a reply to a specific serial should only come from the destination (or the bus server). This is required to ensure that noone else on the bus tries to trick us.

---

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

• include/c/adbus.h
• adbus/reply.c