unix-fd: introduce basic protocol definitions

We introduce a new type code for the unix fds. The data stored in unix
fd fields will be an integer index into the array of fds that are
attached to a specific message. We also introduce a new header field
that stores how many fds belong to the message. And finally we introduce
a new error for messages where the payload and the meta data (i.e. unix
fds read for it) don't match up.

diff --git a/dbus/dbus-protocol.h b/dbus/dbus-protocol.h
index 814deae..117195c 100644 (file)
--- a/dbus/dbus-protocol.h
+++ b/dbus/dbus-protocol.h
@@ -110,6 +110,10 @@ extern "C" {
 #define DBUS_TYPE_SIGNATURE     ((int) 'g')
 /** #DBUS_TYPE_SIGNATURE as a string literal instead of a int literal */
 #define DBUS_TYPE_SIGNATURE_AS_STRING      "g"
+/** Type code marking a unix file descriptor */
+#define DBUS_TYPE_UNIX_FD      ((int) 'h')
+/** #DBUS_TYPE_UNIX_FD as a string literal instead of a int literal */
+#define DBUS_TYPE_UNIX_FD_AS_STRING        "h"
 
 /* Compound types */
 /** Type code marking a D-Bus array type */
@@ -207,6 +211,14 @@ extern "C" {
 /** Number of bits you need in an unsigned to store the max message size */
 #define DBUS_MAXIMUM_MESSAGE_LENGTH_BITS 27
 
+/** The maximum total number of unix fds in a message. Similar
+ * rationale as DBUS_MAXIMUM_MESSAGE_LENGTH. However we divide by four
+ * given that one fd is an int and hence at least 32 bits.
+ */
+#define DBUS_MAXIMUM_MESSAGE_UNIX_FDS (DBUS_MAXIMUM_MESSAGE_LENGTH/4)
+/** Number of bits you need in an unsigned to store the max message unix fds */
+#define DBUS_MAXIMUM_MESSAGE_UNIX_FDS_BITS (DBUS_MAXIMUM_MESSAGE_LENGTH_BITS-2)
+
 /** Depth of recursion in the type tree. This is automatically limited
  * to DBUS_MAXIMUM_SIGNATURE_LENGTH since you could only have an array
  * of array of array of ... that fit in the max signature.  But that's
@@ -276,6 +288,12 @@ extern "C" {
  * Header field code for the type signature of a message.
  */
 #define DBUS_HEADER_FIELD_SIGNATURE      8
+/**
+ * Header field code for the number of unix file descriptors associated
+ * with this message.
+ */
+#define DBUS_HEADER_FIELD_UNIX_FDS       9
+
 
 /**
  * Value of the highest-numbered header field code, can be used to determine
@@ -283,7 +301,7 @@ extern "C" {
  * that unknown codes must be ignored, so check for that before
  * indexing the array.
  */
-#define DBUS_HEADER_FIELD_LAST DBUS_HEADER_FIELD_SIGNATURE
+#define DBUS_HEADER_FIELD_LAST DBUS_HEADER_FIELD_UNIX_FDS
 
 /** Header format is defined as a signature:
  *   byte                            byte order
@@ -415,6 +433,9 @@ extern "C" {
 #define DBUS_ERROR_ADT_AUDIT_DATA_UNKNOWN     "org.freedesktop.DBus.Error.AdtAuditDataUnknown"
 /** There's already an object with the requested object path. */
 #define DBUS_ERROR_OBJECT_PATH_IN_USE         "org.freedesktop.DBus.Error.ObjectPathInUse"
+/** The message meta data does not match the payload. e.g. expected
+    number of file descriptors were not sent over the socket this message was received on. */
+#define DBUS_ERROR_INCONSISTENT_MESSAGE       "org.freedesktop.DBus.Error.InconsistentMessage"
 
 /* XML introspection format */