libpurple/media-gst.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program 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
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_MEDIA_GST_H
  23 #define PURPLE_MEDIA_GST_H
  24 /**
  25  * SECTION:media-gst
  26  * @section_id: libpurple-media-gst
  27  * @short_description: <filename>media-gst.h</filename>
  28  * @title: Media Element API
  29  */
  30
  31 #include "media.h"
  32 #include "mediamanager.h"
  33
  34 #include <gst/gst.h>
  35
  36 #define PURPLE_TYPE_MEDIA_ELEMENT_TYPE  purple_media_element_type_get_type()
  37 #define PURPLE_TYPE_MEDIA_ELEMENT_INFO  purple_media_element_info_get_type()
  38
  39 /**
  40  * PurpleMediaElementInfo:
  41  *
  42  * An opaque structure representing an audio/video source/sink.
  43  */
  44 typedef struct _PurpleMediaElementInfo PurpleMediaElementInfo;
  45
  46 typedef GstElement *(*PurpleMediaElementCreateCallback)(
  47                 PurpleMediaElementInfo *info, PurpleMedia *media,
  48                 const gchar *session_id, const gchar *participant);
  49
  50 /**
  51  * PurpleMediaElementType:
  52  * @PURPLE_MEDIA_ELEMENT_NONE:         empty element
  53  * @PURPLE_MEDIA_ELEMENT_AUDIO:        supports audio
  54  * @PURPLE_MEDIA_ELEMENT_VIDEO:        supports video
  55  * @PURPLE_MEDIA_ELEMENT_AUDIO_VIDEO:  supports audio and video
  56  * @PURPLE_MEDIA_ELEMENT_NO_SRCS:      has no src pads
  57  * @PURPLE_MEDIA_ELEMENT_ONE_SRC:      has one src pad
  58  * @PURPLE_MEDIA_ELEMENT_MULTI_SRC:    has multiple src pads
  59  * @PURPLE_MEDIA_ELEMENT_REQUEST_SRC:  src pads must be requested
  60  * @PURPLE_MEDIA_ELEMENT_NO_SINKS:     has no sink pads
  61  * @PURPLE_MEDIA_ELEMENT_ONE_SINK:     has one sink pad
  62  * @PURPLE_MEDIA_ELEMENT_MULTI_SINK:   has multiple sink pads
  63  * @PURPLE_MEDIA_ELEMENT_REQUEST_SINK: sink pads must be requested
  64  * @PURPLE_MEDIA_ELEMENT_UNIQUE:       This element is unique and only one
  65  *                                     instance of it should be created at a
  66  *                                     time
  67  * @PURPLE_MEDIA_ELEMENT_SRC:          can be set as an active src
  68  * @PURPLE_MEDIA_ELEMENT_SINK:         can be set as an active sink
  69  * @PURPLE_MEDIA_ELEMENT_APPLICATION:  supports application data
  70  */
  71 typedef enum {
  72         PURPLE_MEDIA_ELEMENT_NONE = 0,
  73         PURPLE_MEDIA_ELEMENT_AUDIO = 1,
  74         PURPLE_MEDIA_ELEMENT_VIDEO = 1 << 1,
  75         PURPLE_MEDIA_ELEMENT_AUDIO_VIDEO = PURPLE_MEDIA_ELEMENT_AUDIO
  76                         | PURPLE_MEDIA_ELEMENT_VIDEO,
  77         PURPLE_MEDIA_ELEMENT_NO_SRCS = 0,
  78         PURPLE_MEDIA_ELEMENT_ONE_SRC = 1 << 2,
  79         PURPLE_MEDIA_ELEMENT_MULTI_SRC = 1 << 3,
  80         PURPLE_MEDIA_ELEMENT_REQUEST_SRC = 1 << 4,
  81         PURPLE_MEDIA_ELEMENT_NO_SINKS = 0,
  82         PURPLE_MEDIA_ELEMENT_ONE_SINK = 1 << 5,
  83         PURPLE_MEDIA_ELEMENT_MULTI_SINK = 1 << 6,
  84         PURPLE_MEDIA_ELEMENT_REQUEST_SINK = 1 << 7,
  85         PURPLE_MEDIA_ELEMENT_UNIQUE = 1 << 8,
  86         PURPLE_MEDIA_ELEMENT_SRC = 1 << 9,
  87         PURPLE_MEDIA_ELEMENT_SINK = 1 << 10,
  88         PURPLE_MEDIA_ELEMENT_APPLICATION = 1 << 11,
  89 } PurpleMediaElementType;
  90
  91 G_BEGIN_DECLS
  92
  93 /**
  94  * purple_media_element_type_get_type:
  95  *
  96  * Gets the element type's GType.
  97  *
  98  * Returns: The element type's GType.
  99  */
 100 GType purple_media_element_type_get_type(void);
 101
 102 /**
 103  * purple_media_element_info_get_type:
 104  *
 105  * Gets the element info's GType.
 106  *
 107  * Returns: The element info's GType.
 108  */
 109 G_DECLARE_FINAL_TYPE(PurpleMediaElementInfo, purple_media_element_info, PURPLE,
 110                 MEDIA_ELEMENT_INFO, GObject)
 111
 112 /**
 113  * purple_media_get_src:
 114  * @media: The media object the session is in.
 115  * @sess_id: The session id of the session to get the source from.
 116  *
 117  * Gets the source from a session
 118  *
 119  * Returns: The source retrieved.
 120  */
 121 GstElement *purple_media_get_src(PurpleMedia *media, const gchar *sess_id);
 122
 123 /**
 124  * purple_media_get_tee:
 125  * @media: The instance to get the tee from.
 126  * @session_id: The id of the session to get the tee from.
 127  * @participant: Optionally, the participant of the stream to get the tee from.
 128  *
 129  * Gets the tee from a given session/stream.
 130  *
 131  * Returns: The GstTee element from the chosen session/stream.
 132  */
 133 GstElement *purple_media_get_tee(PurpleMedia *media,
 134                 const gchar *session_id, const gchar *participant);
 135
 136
 137 /**
 138  * purple_media_manager_get_pipeline:
 139  * @manager: The media manager to get the pipeline from.
 140  *
 141  * Gets the pipeline from the media manager.
 142  *
 143  * Returns: (transfer none): The pipeline.
 144  */
 145 GstElement *purple_media_manager_get_pipeline(PurpleMediaManager *manager);
 146
 147 /**
 148  * purple_media_manager_get_element:
 149  * @manager: The media manager to use to obtain the source/sink.
 150  * @type: The type of source/sink to get.
 151  * @media: The media call this element is requested for.
 152  * @session_id: The id of the session this element is requested for or NULL.
 153  * @participant: The remote user this element is requested for or NULL.
 154  *
 155  * Returns: (transfer full): A GStreamer source or sink for audio or video.
 156  */
 157 GstElement *purple_media_manager_get_element(PurpleMediaManager *manager,
 158                 PurpleMediaSessionType type, PurpleMedia *media,
 159                 const gchar *session_id, const gchar *participant);
 160
 161 /**
 162  * purple_media_manager_enumerate_elements:
 163  * @manager: The media manager to use to obtain the element infos.
 164  * @type: The type of element infos to get.
 165  *
 166  * Returns: (transfer container) (element-type PurpleMediaElementInfo): A #GList of registered #PurpleMediaElementInfo instances that match
 167  * @type.
 168  */
 169 GList *purple_media_manager_enumerate_elements(PurpleMediaManager *manager,
 170                 PurpleMediaElementType type);
 171
 172 /**
 173  * purple_media_manager_get_element_info:
 174  * @manager: The #PurpleMediaManager instance
 175  * @name: The name of the element to get.
 176  *
 177  * Returns: (transfer full): The #PurpleMediaElementInfo for @name or NULL.
 178  */
 179 PurpleMediaElementInfo *purple_media_manager_get_element_info(
 180                 PurpleMediaManager *manager, const gchar *name);
 181
 182 gboolean purple_media_manager_register_element(PurpleMediaManager *manager,
 183                 PurpleMediaElementInfo *info);
 184 gboolean purple_media_manager_unregister_element(PurpleMediaManager *manager,
 185                 const gchar *name);
 186 gboolean purple_media_manager_set_active_element(PurpleMediaManager *manager,
 187                 PurpleMediaElementInfo *info);
 188
 189 /**
 190  * purple_media_manager_get_active_element:
 191  * @manager: The #PurpleMediaManager instance
 192  * @type: The #PurpleMediaElementType who's info to get
 193  *
 194  * Returns: (transfer none): The #PurpleMediaElementInfo for @type.
 195  */
 196 PurpleMediaElementInfo *purple_media_manager_get_active_element(
 197                 PurpleMediaManager *manager, PurpleMediaElementType type);
 198
 199 /**
 200  * purple_media_manager_set_video_caps:
 201  * @manager: The media manager to set the media formats.
 202  * @caps: Set of allowed media formats.
 203  *
 204  * Reduces media formats supported by the video source to given set.
 205  *
 206  * Useful to force negotiation of smaller picture resolution more suitable for
 207  * use with particular codec and communication protocol without rescaling.
 208  */
 209 void purple_media_manager_set_video_caps(PurpleMediaManager *manager,
 210                 GstCaps *caps);
 211
 212 /**
 213  * purple_media_manager_get_video_caps:
 214  * @manager: The media manager to get the media formats from.
 215  *
 216  * Returns current set of media formats limiting the output from video source.
 217  *
 218  * Returns: #GstCaps limiting the video source's formats.
 219  */
 220 GstCaps *purple_media_manager_get_video_caps(PurpleMediaManager *manager);
 221
 222 gchar *purple_media_element_info_get_id(PurpleMediaElementInfo *info);
 223 gchar *purple_media_element_info_get_name(PurpleMediaElementInfo *info);
 224 PurpleMediaElementType purple_media_element_info_get_element_type(
 225                 PurpleMediaElementInfo *info);
 226
 227 /**
 228  * purple_media_element_info_call_create:
 229  * @info: The #PurpleMediaElementInfo to create the element from
 230  * @media:
 231  * @session_id:
 232  * @participant:
 233  *
 234  * Returns: (transfer full): The new GstElement.
 235  */
 236 GstElement *purple_media_element_info_call_create(
 237                 PurpleMediaElementInfo *info, PurpleMedia *media,
 238                 const gchar *session_id, const gchar *participant);
 239
 240 G_END_DECLS
 241
 242 #endif /* PURPLE_MEDIA_GST_H */