libpurple/mediamanager.h

   1 /**
   2  * @file mediamanager.h Media Manager API
   3  * @ingroup core
   4  */
   5
   6 /* purple
   7  *
   8  * Purple is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26
  27 #ifndef _PURPLE_MEDIA_MANAGER_H_
  28 #define _PURPLE_MEDIA_MANAGER_H_
  29
  30 #include <glib.h>
  31 #include <glib-object.h>
  32
  33 /** An opaque structure representing a group of (usually all) media calls. */
  34 typedef struct _PurpleMediaManager PurpleMediaManager;
  35 /** The GObject class structure of the PurpleMediaManager object. */
  36 typedef struct _PurpleMediaManagerClass PurpleMediaManagerClass;
  37
  38 #include "account.h"
  39 #include "media.h"
  40
  41 G_BEGIN_DECLS
  42
  43 #define PURPLE_TYPE_MEDIA_MANAGER            (purple_media_manager_get_type())
  44 #define PURPLE_MEDIA_MANAGER(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_MANAGER, PurpleMediaManager))
  45 #define PURPLE_MEDIA_MANAGER_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_MEDIA_MANAGER, PurpleMediaManagerClass))
  46 #define PURPLE_IS_MEDIA_MANAGER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_MEDIA_MANAGER))
  47 #define PURPLE_IS_MEDIA_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA_MANAGER))
  48 #define PURPLE_MEDIA_MANAGER_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA_MANAGER, PurpleMediaManagerClass))
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /**************************************************************************/
  55 /** @name Media Manager API                                              */
  56 /**************************************************************************/
  57 /*@{*/
  58
  59 /**
  60  * Gets the media manager's GType.
  61  *
  62  * @return The media manager's GType.
  63  *
  64  * @since 2.6.0
  65  */
  66 GType purple_media_manager_get_type(void);
  67
  68 /**
  69  * Gets the "global" media manager object. It's created if it doesn't already exist.
  70  *
  71  * @return The "global" instance of the media manager object.
  72  *
  73  * @since 2.6.0
  74  */
  75 PurpleMediaManager *purple_media_manager_get(void);
  76
  77 /**
  78  * Creates a media session.
  79  *
  80  * @param manager The media manager to create the session under.
  81  * @param account The account to create the session on.
  82  * @param conference_type The conference type to feed into Farsight2.
  83  * @param remote_user The remote user to initiate the session with.
  84  * @param initiator TRUE if the local user is the initiator of this media call, FALSE otherwise.
  85  *
  86  * @return A newly created media session.
  87  *
  88  * @since 2.6.0
  89  */
  90 PurpleMedia *purple_media_manager_create_media(PurpleMediaManager *manager,
  91                                                 PurpleAccount *account,
  92                                                 const char *conference_type,
  93                                                 const char *remote_user,
  94                                                 gboolean initiator);
  95
  96 /**
  97  * Gets all of the media sessions.
  98  *
  99  * @param manager The media manager to get all of the sessions from.
 100  *
 101  * @return A list of all the media sessions.
 102  *
 103  * @since 2.6.0
 104  */
 105 GList *purple_media_manager_get_media(PurpleMediaManager *manager);
 106
 107 /**
 108  * Gets all of the media sessions for a given account.
 109  *
 110  * @param manager The media manager to get the sessions from.
 111  * @param account The account the sessions are on.
 112  *
 113  * @return A list of the media sessions on the given account.
 114  *
 115  * @since 2.6.0
 116  */
 117 GList *purple_media_manager_get_media_by_account(
 118                 PurpleMediaManager *manager, PurpleAccount *account);
 119
 120 /**
 121  * Removes a media session from the media manager.
 122  *
 123  * @param manager The media manager to remove the media session from.
 124  * @param media The media session to remove.
 125  *
 126  * @since 2.6.0
 127  */
 128 void
 129 purple_media_manager_remove_media(PurpleMediaManager *manager,
 130                                   PurpleMedia *media);
 131
 132 /**
 133  * Signals that output windows should be created for the chosen stream.
 134  *
 135  * This shouldn't be called outside of mediamanager.c and media.c
 136  *
 137  * @param manager Manager the output windows are registered with.
 138  * @param media Media session the output windows are registered for.
 139  * @param session_id The session the output windows are registered with.
 140  * @param participant The participant the output windows are registered with.
 141  *
 142  * @return TRUE if it succeeded, FALSE if it failed.
 143  *
 144  * @since 2.6.0
 145  */
 146 gboolean purple_media_manager_create_output_window(
 147                 PurpleMediaManager *manager, PurpleMedia *media,
 148                 const gchar *session_id, const gchar *participant);
 149
 150 /**
 151  * Registers a video output window to be created for a given stream.
 152  *
 153  * @param manager The manager to register the output window with.
 154  * @param media The media instance to find the stream in.
 155  * @param session_id The session the stream is associated with.
 156  * @param participant The participant the stream is associated with.
 157  * @param window_id The window ID to embed the video in.
 158  *
 159  * @return A unique ID to the registered output window, 0 if it failed.
 160  *
 161  * @since 2.6.0
 162  */
 163 gulong purple_media_manager_set_output_window(PurpleMediaManager *manager,
 164                 PurpleMedia *media, const gchar *session_id,
 165                 const gchar *participant, gulong window_id);
 166
 167 /**
 168  * Remove a previously registerd output window.
 169  *
 170  * @param manager The manager the output window was registered with.
 171  * @param output_window_id The ID of the output window.
 172  *
 173  * @return TRUE if it found the output window and was successful, else FALSE.
 174  *
 175  * @since 2.6.0
 176  */
 177 gboolean purple_media_manager_remove_output_window(
 178                 PurpleMediaManager *manager, gulong output_window_id);
 179
 180 /**
 181  * Remove all output windows for a given conference/session/participant/stream.
 182  *
 183  * @param manager The manager the output windows were registered with.
 184  * @param media The media instance the output windows were registered for.
 185  * @param session_id The session the output windows were registered for.
 186  * @param participant The participant the output windows were registered for.
 187  *
 188  * @since 2.6.0
 189  */
 190 void purple_media_manager_remove_output_windows(
 191                 PurpleMediaManager *manager, PurpleMedia *media,
 192                 const gchar *session_id, const gchar *participant);
 193
 194 /**
 195  * Sets which media caps the UI supports.
 196  *
 197  * @param manager The manager to set the caps on.
 198  * @param caps The caps to set.
 199  *
 200  * @since 2.6.0
 201  */
 202 void purple_media_manager_set_ui_caps(PurpleMediaManager *manager,
 203                 PurpleMediaCaps caps);
 204
 205 /**
 206  * Gets which media caps the UI supports.
 207  *
 208  * @param manager The manager to get caps from.
 209  *
 210  * @return caps The caps retrieved.
 211  *
 212  * @since 2.6.0
 213  */
 214 PurpleMediaCaps purple_media_manager_get_ui_caps(PurpleMediaManager *manager);
 215
 216 /**
 217  * Sets which media backend type media objects will use.
 218  *
 219  * @param manager The manager to set the caps on.
 220  * @param backend_type The media backend type to use.
 221  *
 222  * @since 2.7.0
 223  */
 224 void purple_media_manager_set_backend_type(PurpleMediaManager *manager,
 225                 GType backend_type);
 226
 227 /**
 228  * Gets which media backend type media objects will use.
 229  *
 230  * @param manager The manager to get the media backend type from.
 231  *
 232  * @return The type of media backend type media objects will use.
 233  *
 234  * @since 2.7.0
 235  */
 236 GType purple_media_manager_get_backend_type(PurpleMediaManager *manager);
 237
 238 /*}@*/
 239
 240 #ifdef __cplusplus
 241 }
 242 #endif
 243
 244 G_END_DECLS
 245
 246 #endif  /* _PURPLE_MEDIA_MANAGER_H_ */