From fd276b482071a84b89bcf4def0f1cd45586b7c90 Mon Sep 17 00:00:00 2001
From: Wim Taymans <wtaymans@redhat.com>
Date: Mon, 31 Aug 2015 17:10:44 +0200
Subject: [PATCH] add continuation packet

Add continuation type packet that would make it possible to send
commands using a piece of shared memory.
---
 doc/design.txt      | 31 +++++++++++++++++++++++--------
 src/client/buffer.h | 13 ++++++++-----
 2 files changed, 31 insertions(+), 13 deletions(-)

diff --git a/doc/design.txt b/doc/design.txt
index 682e3b847..5a1e3fa1e 100644
--- a/doc/design.txt
+++ b/doc/design.txt
@@ -55,18 +55,27 @@ Wire
 
 Fixed header
 
-<version>     : 4 bytes       : total message length
+<version>     : 4 bytes       : message version
 <length>      : 4 bytes       : total message length
 
 Followed by 1 or more type-length-data sections
 
 <type>   : 1 byte
-<length> : variable length, 7 bits, hight bit is continuation marker
+<length> : variable length, 7 bits, high bit is continuation marker
 <data>   : <length> bytes, see below for contents based on <type>
 
 Types:
 
- 1: header
+ 1: continuation section
+
+   Rest of the commands can be found in the shared memory region at
+   @offset and @size. A shared memory region is negotiated when the client
+   connects to the server.
+
+   <offset>     : 8 bytes      : offset
+   <size>       : 8 bytes      : size
+
+ 2: header
 
    Header for payload
 
@@ -75,27 +84,33 @@ Types:
    <pts>        : 8 bytes      : presentation time
    <dts-offset> : 8 bytes      : dts-offset
 
- 2: fd-payload section
+ 3: fd-payload section
 
-   Used to send a buffer between client and server.
+   Used to send a block of data between client and server. The type of fd and
+   the possible operations on it are negotiated when the client connects.
 
    <id>         : 4 bytes      : id of the fd-payload
    <offset>     : 8 bytes      : offset
    <size>       : 8 bytes      : size
    <fd-index>   : 4 bytes      : index of fd
 
- 3: release fd-payload
+ 4: release fd-payload
 
    Release a fd-payload with <id>
 
    <id>         : 4 bytes      : the id number of the released fd-payload
 
- 4: format change
+ 5: format change
+
+   Perform an in-band format change. The following data blocks will be in this
+   new format.
 
    <format-id>  : 1 byte       : format id
    <format>     : 0-terminated : contains serialized format
 
- 5: property changes
+ 6: property changes
+
+   Notify a property change.
 
    <key>       : 0-terminated   : key
    <value>     : 0-terminated   : value
diff --git a/src/client/buffer.h b/src/client/buffer.h
index 167ac2ee5..03dc08cc1 100644
--- a/src/client/buffer.h
+++ b/src/client/buffer.h
@@ -56,6 +56,8 @@ gpointer           pinos_buffer_steal            (PinosBuffer       *buffer,
 /**
  * PinosPacketType:
  * @PINOS_PACKET_TYPE_INVALID: invalid packet type, ignore
+ * @PINOS_PACKET_TYPE_CONTINUATION: continuation packet, used internally to send
+ *      commands using a shared memory region.
  * @PINOS_PACKET_TYPE_HEADER: common packet header
  * @PINOS_PACKET_TYPE_FD_PAYLOAD: packet contains fd-payload. An fd-payload contains
  *      the media data as a file descriptor
@@ -69,11 +71,12 @@ gpointer           pinos_buffer_steal            (PinosBuffer       *buffer,
 typedef enum {
   PINOS_PACKET_TYPE_INVALID            = 0,
 
-  PINOS_PACKET_TYPE_HEADER             = 1,
-  PINOS_PACKET_TYPE_FD_PAYLOAD         = 2,
-  PINOS_PACKET_TYPE_RELEASE_FD_PAYLOAD = 3,
-  PINOS_PACKET_TYPE_FORMAT_CHANGE      = 4,
-  PINOS_PACKET_TYPE_PROPERTY_CHANGE    = 5,
+  PINOS_PACKET_TYPE_CONTINUATION       = 1,
+  PINOS_PACKET_TYPE_HEADER             = 2,
+  PINOS_PACKET_TYPE_FD_PAYLOAD         = 3,
+  PINOS_PACKET_TYPE_RELEASE_FD_PAYLOAD = 4,
+  PINOS_PACKET_TYPE_FORMAT_CHANGE      = 5,
+  PINOS_PACKET_TYPE_PROPERTY_CHANGE    = 6,
 } PinosPacketType;