1 /* GStreamer
2 * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
3 * Copyright (C) <2004> Thomas Vander Stichele <thomas at apestaart dot org>
4 *
5 * dataprotocol.c: Functions implementing the GStreamer Data Protocol
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
21 */
23 #ifdef HAVE_CONFIG_H
24 #include "config.h"
25 #endif
27 #include <gst/gst.h>
28 #include <gst/dataprotocol/dataprotocol.h>
29 #include <glib/gprintf.h> /* g_sprintf */
30 #include <string.h> /* strlen */
31 #include "dp-private.h"
33 /* debug category */
34 GST_DEBUG_CATEGORY (data_protocol_debug);
35 #define GST_CAT_DEFAULT data_protocol_debug
37 /* calculate a CCITT 16 bit CRC check value for a given byte array */
38 /*
39 * this code snippet is adapted from a web page I found
40 * it is identical except for cleanups, and a final XOR with 0xffff
41 * as outlined in the uecp spec
42 *
43 * XMODEM x^16 + x^12 + x^5 + 1
44 */
46 #define POLY 0x1021
47 #define CRC_INIT 0xFFFF
49 static guint16
50 gst_dp_crc (const guint8 * buffer, register guint length)
51 {
52 static gboolean initialized = FALSE;
53 static guint16 crc_table[256];
54 guint16 crc_register;
55 unsigned long i, j, k;
57 if (!initialized) {
58 for (i = 0; i < 256; i++) {
59 j = i << 8;
60 for (k = 8; k--;) {
61 j = j & 0x8000 ? (j << 1) ^ POLY : j << 1;
62 }
64 crc_table[i] = (guint16) j;
65 }
66 initialized = TRUE;
67 }
69 crc_register = CRC_INIT; /* always init register */
71 /* calc CRC */
72 for (; length--;) {
73 crc_register = (guint16) ((crc_register << 8) ^
74 crc_table[((crc_register >> 8) & 0x00ff) ^ *buffer++]);
75 }
76 return (0xffff ^ crc_register);
77 }
79 /* debugging function; dumps byte array values per 8 bytes */
80 /* FIXME: would be nice to merge this with gst_util_dump_mem () */
81 void
82 gst_dp_dump_byte_array (guint8 * array, guint length)
83 {
84 int i;
85 int n = 8; /* number of bytes per line */
86 gchar *line = g_malloc (3 * n + 1);
88 GST_LOG ("dumping byte array of length %d", length);
89 for (i = 0; i < length; ++i) {
90 g_sprintf (line + 3 * (i % n), "%02x ", array[i]);
91 if (i % n == (n - 1)) {
92 GST_LOG ("%03d: %s", i - (n - 1), line);
93 }
94 }
95 if (i % n != 0) {
96 GST_LOG ("%03d: %s", (i / n) * n, line);
97 }
98 g_free (line);
99 }
101 /**
102 * gst_dp_init:
103 *
104 * Initialize GStreamer Data Protocol library.
105 *
106 * Should be called before using these functions; either from source linking
107 * to this source file or from plugin_init.
108 */
109 void
110 gst_dp_init (void)
111 {
112 static gboolean _gst_dp_initialized = FALSE;
114 if (_gst_dp_initialized)
115 return;
117 _gst_dp_initialized = TRUE;
119 GST_DEBUG_CATEGORY_INIT (data_protocol_debug, "gdp", 0,
120 "GStreamer Data Protocol");
121 }
123 /*** PUBLIC FUNCTIONS ***/
125 /**
126 * gst_dp_header_payload_length:
127 * @header: the byte header of the packet array
128 *
129 * Returns: the length of the payload this header describes.
130 */
131 guint32
132 gst_dp_header_payload_length (const guint8 * header)
133 {
134 return GST_DP_HEADER_PAYLOAD_LENGTH (header);
135 }
137 /**
138 * gst_dp_header_payload_type:
139 * @header: the byte header of the packet array
140 *
141 * Returns: the #GstDPPayloadType the payload this header describes.
142 */
143 GstDPPayloadType
144 gst_dp_header_payload_type (const guint8 * header)
145 {
146 return GST_DP_HEADER_PAYLOAD_TYPE (header);
147 }
149 /**
150 * gst_dp_header_from_buffer:
151 * @buffer: a #GstBuffer to create a header for
152 * @flags: the #GDPHeaderFlags to create the header with
153 * @length: a guint pointer to store the header length in
154 * @header: a guint8 * pointer to store a newly allocated header byte array in
155 *
156 * Creates a GDP header from the given buffer.
157 *
158 * Returns: %TRUE if the header was successfully created.
159 */
161 gboolean
162 gst_dp_header_from_buffer (const GstBuffer * buffer, GstDPHeaderFlag flags,
163 guint * length, guint8 ** header)
164 {
165 guint8 *h;
166 guint16 crc;
167 guint16 flags_mask;
169 g_return_val_if_fail (GST_IS_BUFFER (buffer), FALSE);
170 g_return_val_if_fail (header, FALSE);
172 *length = GST_DP_HEADER_LENGTH;
173 h = g_malloc (GST_DP_HEADER_LENGTH);
175 /* version, flags, type */
176 h[0] = (guint8) GST_DP_VERSION_MAJOR;
177 h[1] = (guint8) GST_DP_VERSION_MINOR;
178 h[2] = (guint8) flags;
179 h[3] = GST_DP_PAYLOAD_BUFFER;
181 /* buffer properties */
182 GST_WRITE_UINT32_BE (h + 4, GST_BUFFER_SIZE (buffer));
183 GST_WRITE_UINT64_BE (h + 8, GST_BUFFER_TIMESTAMP (buffer));
184 GST_WRITE_UINT64_BE (h + 16, GST_BUFFER_DURATION (buffer));
185 GST_WRITE_UINT64_BE (h + 24, GST_BUFFER_OFFSET (buffer));
186 GST_WRITE_UINT64_BE (h + 32, GST_BUFFER_OFFSET_END (buffer));
188 /* data flags */
189 /* we only copy KEY_UNIT,DELTA_UNIT and IN_CAPS flags */
190 flags_mask = GST_BUFFER_FLAG_PREROLL | GST_BUFFER_FLAG_IN_CAPS |
191 GST_BUFFER_FLAG_DELTA_UNIT;
193 GST_WRITE_UINT16_BE (h + 40, GST_BUFFER_FLAGS (buffer) & flags_mask);
195 /* ABI padding */
196 GST_WRITE_UINT16_BE (h + 42, (guint64) 0);
197 GST_WRITE_UINT32_BE (h + 44, (guint64) 0);
198 GST_WRITE_UINT64_BE (h + 48, (guint64) 0);
200 /* CRC */
201 crc = 0;
202 if (flags & GST_DP_HEADER_FLAG_CRC_HEADER) {
203 /* we don't crc the last four bytes of the header since they are crc's */
204 crc = gst_dp_crc (h, 56);
205 }
206 GST_WRITE_UINT16_BE (h + 56, crc);
208 crc = 0;
209 if (flags & GST_DP_HEADER_FLAG_CRC_PAYLOAD) {
210 crc = gst_dp_crc (GST_BUFFER_DATA (buffer), GST_BUFFER_SIZE (buffer));
211 }
212 GST_WRITE_UINT16_BE (h + 58, crc);
214 GST_LOG ("created header from buffer:");
215 gst_dp_dump_byte_array (h, GST_DP_HEADER_LENGTH);
216 *header = h;
217 return TRUE;
218 }
220 /**
221 * gst_dp_packet_from_caps:
222 * @caps: a #GstCaps to create a packet for
223 * @flags: the #GDPHeaderFlags to create the header with
224 * @length: a guint pointer to store the header length in
225 * @header: a guint8 pointer to store a newly allocated header byte array in
226 * @payload: a guint8 pointer to store a newly allocated payload byte array in
227 *
228 * Creates a GDP packet from the given caps.
229 *
230 * Returns: %TRUE if the packet was successfully created.
231 */
232 gboolean
233 gst_dp_packet_from_caps (const GstCaps * caps, GstDPHeaderFlag flags,
234 guint * length, guint8 ** header, guint8 ** payload)
235 {
236 guint8 *h;
237 guint16 crc;
238 guchar *string;
240 /* FIXME: GST_IS_CAPS doesn't work
241 g_return_val_if_fail (GST_IS_CAPS (caps), FALSE); */
242 g_return_val_if_fail (caps, FALSE);
243 g_return_val_if_fail (header, FALSE);
244 g_return_val_if_fail (payload, FALSE);
246 *length = GST_DP_HEADER_LENGTH;
247 h = g_malloc (GST_DP_HEADER_LENGTH);
249 string = (guchar *) gst_caps_to_string (caps);
251 /* version, flags, type */
252 h[0] = (guint8) GST_DP_VERSION_MAJOR;
253 h[1] = (guint8) GST_DP_VERSION_MINOR;
254 h[2] = (guint8) flags;
255 h[3] = GST_DP_PAYLOAD_CAPS;
257 /* buffer properties */
258 GST_WRITE_UINT32_BE (h + 4, strlen ((gchar *) string) + 1); /* include trailing 0 */
259 GST_WRITE_UINT64_BE (h + 8, (guint64) 0);
260 GST_WRITE_UINT64_BE (h + 16, (guint64) 0);
261 GST_WRITE_UINT64_BE (h + 24, (guint64) 0);
262 GST_WRITE_UINT64_BE (h + 32, (guint64) 0);
264 /* ABI padding */
265 GST_WRITE_UINT64_BE (h + 40, (guint64) 0);
266 GST_WRITE_UINT64_BE (h + 48, (guint64) 0);
268 /* CRC */
269 crc = 0;
270 if (flags & GST_DP_HEADER_FLAG_CRC_HEADER) {
271 crc = gst_dp_crc (h, 56);
272 }
273 GST_WRITE_UINT16_BE (h + 56, crc);
275 crc = 0;
276 if (flags & GST_DP_HEADER_FLAG_CRC_PAYLOAD) {
277 crc = gst_dp_crc (string, strlen ((gchar *) string) + 1);
278 }
279 GST_WRITE_UINT16_BE (h + 58, crc);
281 GST_LOG ("created header from caps:");
282 gst_dp_dump_byte_array (h, GST_DP_HEADER_LENGTH);
283 *header = h;
284 *payload = string;
285 return TRUE;
286 }
288 /**
289 * gst_dp_packet_from_event:
290 * @event: a #GstEvent to create a packet for
291 * @flags: the #GDPHeaderFlags to create the header with
292 * @length: a guint pointer to store the header length in
293 * @header: a guint8 pointer to store a newly allocated header byte array in
294 * @payload: a guint8 pointer to store a newly allocated payload byte array in
295 *
296 * Creates a GDP packet from the given event.
297 *
298 * Returns: %TRUE if the packet was successfully created.
299 */
300 gboolean
301 gst_dp_packet_from_event (const GstEvent * event, GstDPHeaderFlag flags,
302 guint * length, guint8 ** header, guint8 ** payload)
303 {
304 guint8 *h;
305 guint16 crc;
306 guint pl_length; /* length of payload */
308 g_return_val_if_fail (event, FALSE);
309 g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
310 g_return_val_if_fail (header, FALSE);
311 g_return_val_if_fail (payload, FALSE);
313 *length = GST_DP_HEADER_LENGTH;
314 h = g_malloc0 (GST_DP_HEADER_LENGTH);
316 /* first construct payload, since we need the length */
317 switch (GST_EVENT_TYPE (event)) {
318 case GST_EVENT_UNKNOWN:
319 g_warning ("Unknown event, ignoring");
320 *length = 0;
321 g_free (h);
322 return FALSE;
323 case GST_EVENT_EOS:
324 case GST_EVENT_FLUSH:
325 case GST_EVENT_DISCONTINUOUS:
326 GST_WRITE_UINT64_BE (h + 8, GST_EVENT_TIMESTAMP (event));
327 pl_length = 0;
328 *payload = NULL;
329 break;
330 case GST_EVENT_SEEK:
331 pl_length = 4 + 8 + 8 + 4;
332 *payload = g_malloc0 (pl_length);
333 GST_WRITE_UINT32_BE (*payload, (guint32) GST_EVENT_SEEK_TYPE (event));
334 GST_WRITE_UINT64_BE (*payload + 4,
335 (guint64) GST_EVENT_SEEK_OFFSET (event));
336 GST_WRITE_UINT64_BE (*payload + 12,
337 (guint64) GST_EVENT_SEEK_ENDOFFSET (event));
338 GST_WRITE_UINT32_BE (*payload + 20,
339 (guint32) GST_EVENT_SEEK_ACCURACY (event));
340 break;
341 case GST_EVENT_QOS:
342 case GST_EVENT_SIZE:
343 case GST_EVENT_RATE:
344 case GST_EVENT_NAVIGATION:
345 case GST_EVENT_TAG:
346 g_warning ("Unhandled event type %d, ignoring", GST_EVENT_TYPE (event));
347 return FALSE;
348 default:
349 g_warning ("Unknown event type %d, ignoring", GST_EVENT_TYPE (event));
350 *length = 0;
351 g_free (h);
352 return FALSE;
353 }
355 /* version, flags, type */
356 h[0] = (guint8) GST_DP_VERSION_MAJOR;
357 h[1] = (guint8) GST_DP_VERSION_MINOR;
358 h[2] = (guint8) flags;
359 h[3] = GST_DP_PAYLOAD_EVENT_NONE + GST_EVENT_TYPE (event);
361 /* length */
362 GST_WRITE_UINT32_BE (h + 4, (guint32) pl_length);
363 /* timestamp */
364 GST_WRITE_UINT64_BE (h + 8, GST_EVENT_TIMESTAMP (event));
366 /* ABI padding */
367 GST_WRITE_UINT64_BE (h + 40, (guint64) 0);
368 GST_WRITE_UINT64_BE (h + 48, (guint64) 0);
370 /* CRC */
371 crc = 0;
372 if (flags & GST_DP_HEADER_FLAG_CRC_HEADER) {
373 crc = gst_dp_crc (h, 56);
374 }
375 GST_WRITE_UINT16_BE (h + 56, crc);
377 crc = 0;
378 /* events can have a NULL payload */
379 if (*payload && flags & GST_DP_HEADER_FLAG_CRC_PAYLOAD) {
380 crc = gst_dp_crc (*payload, strlen ((gchar *) * payload) + 1);
381 }
382 GST_WRITE_UINT16_BE (h + 58, crc);
384 GST_LOG ("created header from event:");
385 gst_dp_dump_byte_array (h, GST_DP_HEADER_LENGTH);
386 *header = h;
387 return TRUE;
388 }
391 /**
392 * gst_dp_buffer_from_header:
393 * @header_length: the length of the packet header
394 * @header: the byte array of the packet header
395 *
396 * Creates a newly allocated #GstBuffer from the given header.
397 * The buffer data needs to be copied into it before validating.
398 *
399 * Use this function if you want to pre-allocate a buffer based on the
400 * packet header to read the packet payload in to.
401 *
402 * Returns: %TRUE if the buffer was successfully created.
403 */
404 GstBuffer *
405 gst_dp_buffer_from_header (guint header_length, const guint8 * header)
406 {
407 GstBuffer *buffer;
409 g_return_val_if_fail (GST_DP_HEADER_PAYLOAD_TYPE (header) ==
410 GST_DP_PAYLOAD_BUFFER, FALSE);
411 buffer =
412 gst_buffer_new_and_alloc ((guint) GST_DP_HEADER_PAYLOAD_LENGTH (header));
413 GST_BUFFER_TIMESTAMP (buffer) = GST_DP_HEADER_TIMESTAMP (header);
414 GST_BUFFER_DURATION (buffer) = GST_DP_HEADER_DURATION (header);
415 GST_BUFFER_OFFSET (buffer) = GST_DP_HEADER_OFFSET (header);
416 GST_BUFFER_OFFSET_END (buffer) = GST_DP_HEADER_OFFSET_END (header);
417 GST_BUFFER_FLAGS (buffer) = GST_DP_HEADER_BUFFER_FLAGS (header);
419 return buffer;
420 }
422 /**
423 * gst_dp_caps_from_packet:
424 * @header_length: the length of the packet header
425 * @header: the byte array of the packet header
426 * @payload: the byte array of the packet payload
427 *
428 * Creates a newly allocated #GstCaps from the given packet.
429 *
430 * Returns: %TRUE if the caps was successfully created.
431 */
432 GstCaps *
433 gst_dp_caps_from_packet (guint header_length, const guint8 * header,
434 const guint8 * payload)
435 {
436 GstCaps *caps;
437 const gchar *string;
439 g_return_val_if_fail (header, FALSE);
440 g_return_val_if_fail (payload, FALSE);
441 g_return_val_if_fail (GST_DP_HEADER_PAYLOAD_TYPE (header) ==
442 GST_DP_PAYLOAD_CAPS, FALSE);
444 string = (gchar *) payload;
445 caps = gst_caps_from_string (string);
446 return caps;
447 }
449 /**
450 * gst_dp_event_from_packet:
451 * @header_length: the length of the packet header
452 * @header: the byte array of the packet header
453 * @payload: the byte array of the packet payload
454 *
455 * Creates a newly allocated #GstEvent from the given packet.
456 *
457 * Returns: %TRUE if the event was successfully created.
458 */
459 GstEvent *
460 gst_dp_event_from_packet (guint header_length, const guint8 * header,
461 const guint8 * payload)
462 {
463 GstEvent *event = NULL;
464 GstEventType type;
466 g_return_val_if_fail (header, FALSE);
467 /* payload can be NULL, e.g. for an EOS event */
469 type = GST_DP_HEADER_PAYLOAD_TYPE (header) - GST_DP_PAYLOAD_EVENT_NONE;
470 switch (type) {
471 case GST_EVENT_UNKNOWN:
472 g_warning ("Unknown event, ignoring");
473 return FALSE;
474 case GST_EVENT_EOS:
475 case GST_EVENT_FLUSH:
476 case GST_EVENT_DISCONTINUOUS:
477 event = gst_event_new (type);
478 GST_EVENT_TIMESTAMP (event) = GST_DP_HEADER_TIMESTAMP (header);
479 break;
480 case GST_EVENT_SEEK:
481 {
482 GstSeekType type;
483 gint64 offset, endoffset;
484 GstSeekAccuracy accuracy;
486 type = (GstSeekType) GST_READ_UINT32_BE (payload);
487 offset = (gint64) GST_READ_UINT64_BE (payload + 4);
488 endoffset = (gint64) GST_READ_UINT64_BE (payload + 12);
489 accuracy = (GstSeekAccuracy) GST_READ_UINT32_BE (payload + 20);
490 event = gst_event_new_segment_seek (type, offset, endoffset);
491 GST_EVENT_TIMESTAMP (event) = GST_DP_HEADER_TIMESTAMP (header);
492 GST_EVENT_SEEK_ACCURACY (event) = accuracy;
493 break;
494 }
495 case GST_EVENT_QOS:
496 case GST_EVENT_SIZE:
497 case GST_EVENT_RATE:
498 case GST_EVENT_NAVIGATION:
499 case GST_EVENT_TAG:
500 g_warning ("Unhandled event type %d, ignoring", GST_EVENT_TYPE (event));
501 return FALSE;
502 default:
503 g_warning ("Unknown event type %d, ignoring", GST_EVENT_TYPE (event));
504 return FALSE;
505 }
507 return event;
508 }
510 /**
511 * gst_dp_validate_header:
512 * @header_length: the length of the packet header
513 * @header: the byte array of the packet header
514 *
515 * Validates the given packet header by checking the CRC checksum.
516 *
517 * Returns: %TRUE if the CRC matches, or no CRC checksum is present.
518 */
519 gboolean
520 gst_dp_validate_header (guint header_length, const guint8 * header)
521 {
522 guint16 crc_read, crc_calculated;
524 if (!(GST_DP_HEADER_FLAGS (header) & GST_DP_HEADER_FLAG_CRC_HEADER))
525 return TRUE;
526 crc_read = GST_DP_HEADER_CRC_HEADER (header);
527 /* don't included the last two crc fields for the crc check */
528 crc_calculated = gst_dp_crc (header, header_length - 4);
529 if (crc_read != crc_calculated) {
530 GST_WARNING ("header crc mismatch: read %02x, calculated %02x", crc_read,
531 crc_calculated);
532 return FALSE;
533 }
534 GST_LOG ("header crc validation: %02x", crc_read);
535 return TRUE;
536 }
538 /**
539 * gst_dp_validate_payload:
540 * @header_length: the length of the packet header
541 * @header: the byte array of the packet header
542 * @payload: the byte array of the packet payload
543 *
544 * Validates the given packet payload using the given packet header
545 * by checking the CRC checksum.
546 *
547 * Returns: %TRUE if the CRC matches, or no CRC checksum is present.
548 */
549 gboolean
550 gst_dp_validate_payload (guint header_length, const guint8 * header,
551 const guint8 * payload)
552 {
553 guint16 crc_read, crc_calculated;
555 if (!(GST_DP_HEADER_FLAGS (header) & GST_DP_HEADER_FLAG_CRC_PAYLOAD))
556 return TRUE;
557 crc_read = GST_DP_HEADER_CRC_PAYLOAD (header);
558 crc_calculated = gst_dp_crc (payload, GST_DP_HEADER_PAYLOAD_LENGTH (header));
559 if (crc_read != crc_calculated) {
560 GST_WARNING ("payload crc mismatch: read %02x, calculated %02x", crc_read,
561 crc_calculated);
562 return FALSE;
563 }
564 GST_LOG ("payload crc validation: %02x", crc_read);
565 return TRUE;
566 }
568 /**
569 * gst_dp_validate_packet:
570 * @header_length: the length of the packet header
571 * @header: the byte array of the packet header
572 * @payload: the byte array of the packet payload
573 *
574 * Validates the given packet by checking version information and checksums.
575 *
576 * Returns: %TRUE if the packet validates.
577 */
578 gboolean
579 gst_dp_validate_packet (guint header_length, const guint8 * header,
580 const guint8 * payload)
581 {
582 if (!gst_dp_validate_header (header_length, header))
583 return FALSE;
584 if (!gst_dp_validate_payload (header_length, header, payload))
585 return FALSE;
587 return TRUE;
588 }
590 /*** PLUGIN STUFF ***/
591 static gboolean
592 plugin_init (GstPlugin * plugin)
593 {
594 gst_dp_init ();
596 return TRUE;
597 }
599 GST_PLUGIN_DEFINE (GST_VERSION_MAJOR,
600 GST_VERSION_MINOR,
601 "gstdataprotocol",
602 "a data protocol to serialize buffers, caps and events",
603 plugin_init, VERSION, GST_LICENSE, GST_PACKAGE, GST_ORIGIN)