Prototypes for functions for chunked writes of audio/video instructions over a guac_socket.

libguac/include/protocol.h

@@ -291,7 +291,66 @@ int guac_protocol_send_audio(guac_socket* socket, int channel,
         const char* mimetype, int duration, void* data, int size);
 
 /**
- * Sends an video instruction over the given guac_socket connection.
+ * Begins a audio instruction over the given guac_socket connection. Only the
+ * initial non-data part of the instruction and the length of the data part
+ * of the instruction are sent. The actual contents of the data must be
+ * sent with guac_protocol_send_audio_data(), and the instruction must be
+ * completed with guac_protocol_send_audio_end().
+ *
+ * Note that the size of the audio to be sent MUST be known ahead of time,
+ * even though the data of the audio may be sent in chunks.
+ *
+ * No further instruction data may be sent along the givven guac_socket
+ * except via guac_protocol_send_audio_data() until the audio instruction
+ * is completed with guac_protocol_send_audio_end().
+ *
+ * If an error occurs sending the instruction, a non-zero value is
+ * returned, and guac_error is set appropriately.
+ *
+ * @param socket The guac_socket connection to use.
+ * @param channel The index of the audio channel the sound should play on.
+ * @param mimetype The mimetype of the data being sent.
+ * @param duration The duration of the audio being sent, in milliseconds.
+ * @param size The number of bytes of audio data to send.
+ * @return Zero on success, non-zero on error.
+ */
+int guac_protocol_send_audio_header(guac_socket* socket,
+        int channel, const char* mimetype, int duration, int size);
+
+/**
+ * Writes a block of audio data to the currently in-progress audio instruction
+ * which was started with guac_protocol_send_audio_header(). Exactly the
+ * number of requested bytes are written unless an error occurs. This function
+ * may be called multiple times per audio instruction for each chunk of audio
+ * data being written, allowing the potentially huge audio instruction to be
+ * split across multiple writes.
+ *
+ * If an error occurs sending the instruction, a non-zero value is
+ * returned, and guac_error is set appropriately.
+ *
+ * @param socket The guac_socket connection to use.
+ * @param data The audio data to write.
+ * @param count The number of bytes within the given buffer of audio data
+ *              that must be written.
+ * @return Zero on success, non-zero on error.
+ */
+int guac_protocol_send_audio_data(guac_socket* socket, void* data, int count);
+
+/**
+ * Completes the audio instruction which was started with
+ * guac_protocol_send_audio_header(), and whose data has been written with
+ * guac_protocol_send_audio_data().
+ *
+ * If an error occurs sending the instruction, a non-zero value is
+ * returned, and guac_error is set appropriately.
+ *
+ * @param socket The guac_socket connection to use.
+ * @return Zero on success, non-zero on error.
+ */
+int guac_protocol_send_audio_end(guac_socket* socket);
+
+/**
+ * Sends a video instruction over the given guac_socket connection.
  *
  * If an error occurs sending the instruction, a non-zero value is
  * returned, and guac_error is set appropriately.
@@ -307,6 +366,65 @@ int guac_protocol_send_audio(guac_socket* socket, int channel,
 int guac_protocol_send_video(guac_socket* socket, const guac_layer* layer,
         const char* mimetype, int duration, void* data, int size);
 
+/**
+ * Begins a video instruction over the given guac_socket connection. Only the
+ * initial non-data part of the instruction and the length of the data part
+ * of the instruction are sent. The actual contents of the data must be
+ * sent with guac_protocol_send_video_data(), and the instruction must be
+ * completed with guac_protocol_send_video_end().
+ *
+ * Note that the size of the video to be sent MUST be known ahead of time,
+ * even though the data of the video may be sent in chunks.
+ *
+ * No further instruction data may be sent along the givven guac_socket
+ * except via guac_protocol_send_video_data() until the video instruction
+ * is completed with guac_protocol_send_video_end().
+ *
+ * If an error occurs sending the instruction, a non-zero value is
+ * returned, and guac_error is set appropriately.
+ *
+ * @param socket The guac_socket connection to use.
+ * @param layer The destination layer.
+ * @param mimetype The mimetype of the data being sent.
+ * @param duration The duration of the video being sent, in milliseconds.
+ * @param size The number of bytes of video data to send.
+ * @return Zero on success, non-zero on error.
+ */
+int guac_protocol_send_video_header(guac_socket* socket,
+        const guac_layer* layer, const char* mimetype, int duration, int size);
+
+/**
+ * Writes a block of video data to the currently in-progress video instruction
+ * which was started with guac_protocol_send_video_header(). Exactly the
+ * number of requested bytes are written unless an error occurs. This function
+ * may be called multiple times per video instruction for each chunk of video
+ * data being written, allowing the potentially huge video instruction to be
+ * split across multiple writes.
+ *
+ * If an error occurs sending the instruction, a non-zero value is
+ * returned, and guac_error is set appropriately.
+ *
+ * @param socket The guac_socket connection to use.
+ * @param data The video data to write.
+ * @param count The number of bytes within the given buffer of video data
+ *              that must be written.
+ * @return Zero on success, non-zero on error.
+ */
+int guac_protocol_send_video_data(guac_socket* socket, void* data, int count);
+
+/**
+ * Completes the video instruction which was started with
+ * guac_protocol_send_video_header(), and whose data has been written with
+ * guac_protocol_send_video_data().
+ *
+ * If an error occurs sending the instruction, a non-zero value is
+ * returned, and guac_error is set appropriately.
+ *
+ * @param socket The guac_socket connection to use.
+ * @return Zero on success, non-zero on error.
+ */
+int guac_protocol_send_video_end(guac_socket* socket);
+
 /* DRAWING INSTRUCTIONS */
 
 /**