2 * Copyright (C) <2005,2006> Wim Taymans <wim@fluendo.com>
3 * <2006> Lutz Mueller <lutz at topfrose dot de>
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
21 * Unless otherwise indicated, Source Code is licensed under MIT license.
22 * See further explanation attached in License Statement (distributed in the file
25 * Permission is hereby granted, free of charge, to any person obtaining a copy of
26 * this software and associated documentation files (the "Software"), to deal in
27 * the Software without restriction, including without limitation the rights to
28 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
29 * of the Software, and to permit persons to whom the Software is furnished to do
30 * so, subject to the following conditions:
32 * The above copyright notice and this permission notice shall be included in all
33 * copies or substantial portions of the Software.
35 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
36 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
37 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
38 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
39 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
40 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
45 * SECTION:gstrtspmessage
46 * @short_description: RTSP messages
47 * @see_also: gstrtspconnection
51 * Provides methods for creating and parsing request, response and data messages.
55 * Last reviewed on 2007-07-25 (0.10.14)
60 #include <gst/gstutils.h>
61 #include "gstrtspmessage.h"
63 typedef struct _RTSPKeyValue
65 GstRTSPHeaderField field;
70 key_value_foreach (GArray * array, GFunc func, gpointer user_data)
74 g_return_if_fail (array != NULL);
76 for (i = 0; i < array->len; i++) {
77 (*func) (&g_array_index (array, RTSPKeyValue, i), user_data);
82 * gst_rtsp_message_new:
83 * @msg: a location for the new #GstRTSPMessage
85 * Create a new initialized #GstRTSPMessage. Free with gst_rtsp_message_free().
87 * Returns: a #GstRTSPResult.
90 gst_rtsp_message_new (GstRTSPMessage ** msg)
92 GstRTSPMessage *newmsg;
94 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
96 newmsg = g_new0 (GstRTSPMessage, 1);
100 return gst_rtsp_message_init (newmsg);
104 * gst_rtsp_message_init:
105 * @msg: a #GstRTSPMessage
107 * Initialize @msg. This function is mostly used when @msg is allocated on the
108 * stack. The reverse operation of this is gst_rtsp_message_unset().
110 * Returns: a #GstRTSPResult.
113 gst_rtsp_message_init (GstRTSPMessage * msg)
115 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
117 gst_rtsp_message_unset (msg);
119 msg->type = GST_RTSP_MESSAGE_INVALID;
120 msg->hdr_fields = g_array_new (FALSE, FALSE, sizeof (RTSPKeyValue));
126 * gst_rtsp_message_get_type:
127 * @msg: a #GstRTSPMessage
129 * Get the message type of @msg.
131 * Returns: the message type.
134 gst_rtsp_message_get_type (GstRTSPMessage * msg)
136 g_return_val_if_fail (msg != NULL, GST_RTSP_MESSAGE_INVALID);
142 * gst_rtsp_message_new_request:
143 * @msg: a location for the new #GstRTSPMessage
144 * @method: the request method to use
145 * @uri: the uri of the request
147 * Create a new #GstRTSPMessage with @method and @uri and store the result
148 * request message in @msg. Free with gst_rtsp_message_free().
150 * Returns: a #GstRTSPResult.
153 gst_rtsp_message_new_request (GstRTSPMessage ** msg, GstRTSPMethod method,
156 GstRTSPMessage *newmsg;
158 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
159 g_return_val_if_fail (uri != NULL, GST_RTSP_EINVAL);
161 newmsg = g_new0 (GstRTSPMessage, 1);
165 return gst_rtsp_message_init_request (newmsg, method, uri);
169 * gst_rtsp_message_init_request:
170 * @msg: a #GstRTSPMessage
171 * @method: the request method to use
172 * @uri: the uri of the request
174 * Initialize @msg as a request message with @method and @uri. To clear @msg
175 * again, use gst_rtsp_message_unset().
177 * Returns: a #GstRTSPResult.
180 gst_rtsp_message_init_request (GstRTSPMessage * msg, GstRTSPMethod method,
183 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
184 g_return_val_if_fail (uri != NULL, GST_RTSP_EINVAL);
186 gst_rtsp_message_unset (msg);
188 msg->type = GST_RTSP_MESSAGE_REQUEST;
189 msg->type_data.request.method = method;
190 msg->type_data.request.uri = g_strdup (uri);
191 msg->type_data.request.version = GST_RTSP_VERSION_1_0;
192 msg->hdr_fields = g_array_new (FALSE, FALSE, sizeof (RTSPKeyValue));
198 * gst_rtsp_message_parse_request:
199 * @msg: a #GstRTSPMessage
200 * @method: location to hold the method
201 * @uri: location to hold the uri
202 * @version: location to hold the version
204 * Parse the request message @msg and store the values @method, @uri and
205 * @version. The result locations can be #NULL if one is not interested in its
208 * @uri remains valid for as long as @msg is valid and unchanged.
210 * Returns: a #GstRTSPResult.
213 gst_rtsp_message_parse_request (GstRTSPMessage * msg,
214 GstRTSPMethod * method, const gchar ** uri, GstRTSPVersion * version)
216 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
217 g_return_val_if_fail (msg->type == GST_RTSP_MESSAGE_REQUEST, GST_RTSP_EINVAL);
220 *method = msg->type_data.request.method;
222 *uri = msg->type_data.request.uri;
224 *version = msg->type_data.request.version;
230 * gst_rtsp_message_new_response:
231 * @msg: a location for the new #GstRTSPMessage
232 * @code: the status code
233 * @reason: the status reason or #NULL
234 * @request: the request that triggered the response or #NULL
236 * Create a new response #GstRTSPMessage with @code and @reason and store the
237 * result message in @msg. Free with gst_rtsp_message_free().
239 * When @reason is #NULL, the default reason for @code will be used.
241 * When @request is not #NULL, the relevant headers will be copied to the new
244 * Returns: a #GstRTSPResult.
247 gst_rtsp_message_new_response (GstRTSPMessage ** msg, GstRTSPStatusCode code,
248 const gchar * reason, const GstRTSPMessage * request)
250 GstRTSPMessage *newmsg;
252 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
254 newmsg = g_new0 (GstRTSPMessage, 1);
258 return gst_rtsp_message_init_response (newmsg, code, reason, request);
262 * gst_rtsp_message_init_response:
263 * @msg: a #GstRTSPMessage
264 * @code: the status code
265 * @reason: the status reason or #NULL
266 * @request: the request that triggered the response or #NULL
268 * Initialize @msg with @code and @reason.
270 * When @reason is #NULL, the default reason for @code will be used.
272 * When @request is not #NULL, the relevant headers will be copied to the new
275 * Returns: a #GstRTSPResult.
278 gst_rtsp_message_init_response (GstRTSPMessage * msg, GstRTSPStatusCode code,
279 const gchar * reason, const GstRTSPMessage * request)
281 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
283 gst_rtsp_message_unset (msg);
286 reason = gst_rtsp_status_as_text (code);
288 msg->type = GST_RTSP_MESSAGE_RESPONSE;
289 msg->type_data.response.code = code;
290 msg->type_data.response.reason = g_strdup (reason);
291 msg->type_data.response.version = GST_RTSP_VERSION_1_0;
292 msg->hdr_fields = g_array_new (FALSE, FALSE, sizeof (RTSPKeyValue));
298 if (gst_rtsp_message_get_header (request, GST_RTSP_HDR_CSEQ, &header,
300 gst_rtsp_message_add_header (msg, GST_RTSP_HDR_CSEQ, header);
303 /* copy session id */
304 if (gst_rtsp_message_get_header (request, GST_RTSP_HDR_SESSION, &header,
308 header = g_strdup (header);
309 if ((pos = strchr (header, ';'))) {
313 gst_rtsp_message_take_header (msg, GST_RTSP_HDR_SESSION, header);
316 /* FIXME copy more headers? */
324 * gst_rtsp_message_parse_response:
325 * @msg: a #GstRTSPMessage
326 * @code: location to hold the status code
327 * @reason: location to hold the status reason
328 * @version: location to hold the version
330 * Parse the response message @msg and store the values @code, @reason and
331 * @version. The result locations can be #NULL if one is not interested in its
334 * @reason remains valid for as long as @msg is valid and unchanged.
336 * Returns: a #GstRTSPResult.
339 gst_rtsp_message_parse_response (GstRTSPMessage * msg,
340 GstRTSPStatusCode * code, const gchar ** reason, GstRTSPVersion * version)
342 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
343 g_return_val_if_fail (msg->type == GST_RTSP_MESSAGE_RESPONSE,
347 *code = msg->type_data.response.code;
349 *reason = msg->type_data.response.reason;
351 *version = msg->type_data.response.version;
357 * gst_rtsp_message_new_data:
358 * @msg: a location for the new #GstRTSPMessage
359 * @channel: the channel
361 * Create a new data #GstRTSPMessage with @channel and store the
362 * result message in @msg. Free with gst_rtsp_message_free().
364 * Returns: a #GstRTSPResult.
367 gst_rtsp_message_new_data (GstRTSPMessage ** msg, guint8 channel)
369 GstRTSPMessage *newmsg;
371 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
373 newmsg = g_new0 (GstRTSPMessage, 1);
377 return gst_rtsp_message_init_data (newmsg, channel);
381 * gst_rtsp_message_init_data:
382 * @msg: a #GstRTSPMessage
383 * @channel: a channel
385 * Initialize a new data #GstRTSPMessage for @channel.
387 * Returns: a #GstRTSPResult.
390 gst_rtsp_message_init_data (GstRTSPMessage * msg, guint8 channel)
392 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
394 gst_rtsp_message_unset (msg);
396 msg->type = GST_RTSP_MESSAGE_DATA;
397 msg->type_data.data.channel = channel;
403 * gst_rtsp_message_parse_data:
404 * @msg: a #GstRTSPMessage
405 * @channel: location to hold the channel
407 * Parse the data message @msg and store the channel in @channel.
409 * Returns: a #GstRTSPResult.
412 gst_rtsp_message_parse_data (GstRTSPMessage * msg, guint8 * channel)
414 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
415 g_return_val_if_fail (msg->type != GST_RTSP_MESSAGE_DATA, GST_RTSP_EINVAL);
418 *channel = msg->type_data.data.channel;
424 * gst_rtsp_message_unset:
425 * @msg: a #GstRTSPMessage
427 * Unset the concents of @msg so that it becomes an uninitialized
428 * #GstRTSPMessage again. This function is mostly used in combination with
429 * gst_rtsp_message_init_request(), gst_rtsp_message_init_response() and
430 * gst_rtsp_message_init_data() on stack allocated #GstRTSPMessage structures.
432 * Returns: #GST_RTSP_OK.
435 gst_rtsp_message_unset (GstRTSPMessage * msg)
437 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
440 case GST_RTSP_MESSAGE_INVALID:
442 case GST_RTSP_MESSAGE_REQUEST:
443 g_free (msg->type_data.request.uri);
445 case GST_RTSP_MESSAGE_RESPONSE:
446 g_free (msg->type_data.response.reason);
448 case GST_RTSP_MESSAGE_DATA:
451 g_return_val_if_reached (GST_RTSP_EINVAL);
454 if (msg->hdr_fields != NULL) {
457 for (i = 0; i < msg->hdr_fields->len; i++) {
458 RTSPKeyValue *keyval = &g_array_index (msg->hdr_fields, RTSPKeyValue, i);
460 g_free (keyval->value);
462 g_array_free (msg->hdr_fields, TRUE);
466 memset (msg, 0, sizeof *msg);
472 * gst_rtsp_message_free:
473 * @msg: a #GstRTSPMessage
475 * Free the memory used by @msg.
477 * Returns: a #GstRTSPResult.
480 gst_rtsp_message_free (GstRTSPMessage * msg)
484 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
486 res = gst_rtsp_message_unset (msg);
487 if (res == GST_RTSP_OK)
494 * gst_rtsp_message_take_header:
495 * @msg: a #GstRTSPMessage
496 * @field: a #GstRTSPHeaderField
497 * @value: the value of the header
499 * Add a header with key @field and @value to @msg. This function takes
500 * ownership of @value.
502 * Returns: a #GstRTSPResult.
507 gst_rtsp_message_take_header (GstRTSPMessage * msg, GstRTSPHeaderField field,
510 RTSPKeyValue key_value;
512 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
513 g_return_val_if_fail (value != NULL, GST_RTSP_EINVAL);
515 key_value.field = field;
516 key_value.value = value;
518 g_array_append_val (msg->hdr_fields, key_value);
524 * gst_rtsp_message_add_header:
525 * @msg: a #GstRTSPMessage
526 * @field: a #GstRTSPHeaderField
527 * @value: the value of the header
529 * Add a header with key @field and @value to @msg. This function takes a copy
532 * Returns: a #GstRTSPResult.
535 gst_rtsp_message_add_header (GstRTSPMessage * msg, GstRTSPHeaderField field,
538 return gst_rtsp_message_take_header (msg, field, g_strdup (value));
542 * gst_rtsp_message_remove_header:
543 * @msg: a #GstRTSPMessage
544 * @field: a #GstRTSPHeaderField
545 * @indx: the index of the header
547 * Remove the @indx header with key @field from @msg. If @indx equals -1, all
548 * headers will be removed.
550 * Returns: a #GstRTSPResult.
553 gst_rtsp_message_remove_header (GstRTSPMessage * msg, GstRTSPHeaderField field,
556 GstRTSPResult res = GST_RTSP_ENOTIMPL;
560 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
562 while (i < msg->hdr_fields->len) {
563 RTSPKeyValue *key_value = &g_array_index (msg->hdr_fields, RTSPKeyValue, i);
565 if (key_value->field == field && (indx == -1 || cnt++ == indx)) {
566 g_free (key_value->value);
567 g_array_remove_index (msg->hdr_fields, i);
579 * gst_rtsp_message_get_header:
580 * @msg: a #GstRTSPMessage
581 * @field: a #GstRTSPHeaderField
582 * @value: pointer to hold the result
583 * @indx: the index of the header
585 * Get the @indx header value with key @field from @msg. The result in @value
586 * stays valid as long as it remains present in @msg.
588 * Returns: #GST_RTSP_OK when @field was found, #GST_RTSP_ENOTIMPL if the key
592 gst_rtsp_message_get_header (const GstRTSPMessage * msg,
593 GstRTSPHeaderField field, gchar ** value, gint indx)
598 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
600 /* no header initialized, there are no headers */
601 if (msg->hdr_fields == NULL)
602 return GST_RTSP_ENOTIMPL;
604 for (i = 0; i < msg->hdr_fields->len; i++) {
605 RTSPKeyValue *key_value = &g_array_index (msg->hdr_fields, RTSPKeyValue, i);
607 if (key_value->field == field && cnt++ == indx) {
609 *value = key_value->value;
614 return GST_RTSP_ENOTIMPL;
618 * gst_rtsp_message_append_headers:
619 * @msg: a #GstRTSPMessage
622 * Append the currently configured headers in @msg to the #GString @str suitable
625 * Returns: #GST_RTSP_OK.
628 gst_rtsp_message_append_headers (const GstRTSPMessage * msg, GString * str)
632 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
633 g_return_val_if_fail (str != NULL, GST_RTSP_EINVAL);
635 for (i = 0; i < msg->hdr_fields->len; i++) {
636 RTSPKeyValue *key_value;
639 key_value = &g_array_index (msg->hdr_fields, RTSPKeyValue, i);
640 keystr = gst_rtsp_header_as_text (key_value->field);
642 g_string_append_printf (str, "%s: %s\r\n", keystr, key_value->value);
648 * gst_rtsp_message_set_body:
649 * @msg: a #GstRTSPMessage
651 * @size: the size of @data
653 * Set the body of @msg to a copy of @data.
655 * Returns: #GST_RTSP_OK.
658 gst_rtsp_message_set_body (GstRTSPMessage * msg, const guint8 * data,
661 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
663 return gst_rtsp_message_take_body (msg, g_memdup (data, size), size);
667 * gst_rtsp_message_take_body:
668 * @msg: a #GstRTSPMessage
670 * @size: the size of @data
672 * Set the body of @msg to @data and @size. This method takes ownership of
675 * Returns: #GST_RTSP_OK.
678 gst_rtsp_message_take_body (GstRTSPMessage * msg, guint8 * data, guint size)
680 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
681 g_return_val_if_fail (data != NULL || size == 0, GST_RTSP_EINVAL);
687 msg->body_size = size;
693 * gst_rtsp_message_get_body:
694 * @msg: a #GstRTSPMessage
695 * @data: location for the data
696 * @size: location for the size of @data
698 * Get the body of @msg. @data remains valid for as long as @msg is valid and
701 * Returns: #GST_RTSP_OK.
704 gst_rtsp_message_get_body (const GstRTSPMessage * msg, guint8 ** data,
707 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
708 g_return_val_if_fail (data != NULL, GST_RTSP_EINVAL);
709 g_return_val_if_fail (size != NULL, GST_RTSP_EINVAL);
712 *size = msg->body_size;
718 * gst_rtsp_message_steal_body:
719 * @msg: a #GstRTSPMessage
720 * @data: location for the data
721 * @size: location for the size of @data
723 * Take the body of @msg and store it in @data and @size. After this method,
724 * the body and size of @msg will be set to #NULL and 0 respectively.
726 * Returns: #GST_RTSP_OK.
729 gst_rtsp_message_steal_body (GstRTSPMessage * msg, guint8 ** data, guint * size)
731 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
732 g_return_val_if_fail (data != NULL, GST_RTSP_EINVAL);
733 g_return_val_if_fail (size != NULL, GST_RTSP_EINVAL);
736 *size = msg->body_size;
745 dump_key_value (gpointer data, gpointer user_data)
747 RTSPKeyValue *key_value = (RTSPKeyValue *) data;
749 g_print (" key: '%s', value: '%s'\n",
750 gst_rtsp_header_as_text (key_value->field), key_value->value);
754 * gst_rtsp_message_dump:
755 * @msg: a #GstRTSPMessage
757 * Dump the contents of @msg to stdout.
759 * Returns: #GST_RTSP_OK.
762 gst_rtsp_message_dump (GstRTSPMessage * msg)
767 g_return_val_if_fail (msg != NULL, GST_RTSP_EINVAL);
770 case GST_RTSP_MESSAGE_REQUEST:
771 g_print ("RTSP request message %p\n", msg);
772 g_print (" request line:\n");
773 g_print (" method: '%s'\n",
774 gst_rtsp_method_as_text (msg->type_data.request.method));
775 g_print (" uri: '%s'\n", msg->type_data.request.uri);
776 g_print (" version: '%s'\n",
777 gst_rtsp_version_as_text (msg->type_data.request.version));
778 g_print (" headers:\n");
779 key_value_foreach (msg->hdr_fields, dump_key_value, NULL);
780 g_print (" body:\n");
781 gst_rtsp_message_get_body (msg, &data, &size);
782 gst_util_dump_mem (data, size);
784 case GST_RTSP_MESSAGE_RESPONSE:
785 g_print ("RTSP response message %p\n", msg);
786 g_print (" status line:\n");
787 g_print (" code: '%d'\n", msg->type_data.response.code);
788 g_print (" reason: '%s'\n", msg->type_data.response.reason);
789 g_print (" version: '%s'\n",
790 gst_rtsp_version_as_text (msg->type_data.response.version));
791 g_print (" headers:\n");
792 key_value_foreach (msg->hdr_fields, dump_key_value, NULL);
793 gst_rtsp_message_get_body (msg, &data, &size);
794 g_print (" body: length %d\n", size);
795 gst_util_dump_mem (data, size);
797 case GST_RTSP_MESSAGE_DATA:
798 g_print ("RTSP data message %p\n", msg);
799 g_print (" channel: '%d'\n", msg->type_data.data.channel);
800 g_print (" size: '%d'\n", msg->body_size);
801 gst_rtsp_message_get_body (msg, &data, &size);
802 gst_util_dump_mem (data, size);
805 g_print ("unsupported message type %d\n", msg->type);
806 return GST_RTSP_EINVAL;