Mercurialadium-1.4 / file revision
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
Frameworks/libpurple.framework/Versions/0.6.2/Headers/switchboard.h
author Zachary West <zacw@adium.im>
Fri Aug 21 13:25:11 2009 -0700 (2009-08-21)
changeset 2592 e8d15275025e
parent 2535 Frameworks/libpurple.framework/Versions/0.6.0/Headers/switchboard.h@39c3c161de14
permissions -rw-r--r--
im.pidgin.adium.1-4 at 267c6165e02e34318a1823960bd04c0639952f73 
     1 /**
     2  * @file switchboard.h MSN switchboard functions
     3  *
     4  * purple
     5  *
     6  * Purple is the legal property of its developers, whose names are too numerous
     7  * to list here.  Please refer to the COPYRIGHT file distributed with this
     8  * source distribution.
     9  *
    10  * This program is free software; you can redistribute it and/or modify
    11  * it under the terms of the GNU General Public License as published by
    12  * the Free Software Foundation; either version 2 of the License, or
    13  * (at your option) any later version.
    14  *
    15  * This program is distributed in the hope that it will be useful,
    16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    18  * GNU General Public License for more details.
    19  *
    20  * You should have received a copy of the GNU General Public License
    21  * along with this program; if not, write to the Free Software
    22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
    23  */
    24 #ifndef _MSN_SWITCHBOARD_H_
    25 #define _MSN_SWITCHBOARD_H_
    26 
    27 typedef struct _MsnSwitchBoard MsnSwitchBoard;
    28 
    29 #include "conversation.h"
    30 
    31 #include "msg.h"
    32 #include "user.h"
    33 
    34 #include "servconn.h"
    35 
    36 #include "slplink.h"
    37 
    38 /**
    39  * A switchboard error.
    40  */
    41 typedef enum
    42 {
    43 	MSN_SB_ERROR_NONE, /**< No error. */
    44 	MSN_SB_ERROR_CAL, /**< The user could not join (answer the call). */
    45 	MSN_SB_ERROR_OFFLINE, /**< The account is offline. */
    46 	MSN_SB_ERROR_USER_OFFLINE, /**< The user to call is offline. */
    47 	MSN_SB_ERROR_CONNECTION, /**< There was a connection error. */
    48 	MSN_SB_ERROR_TOO_FAST, /**< We are sending too fast */
    49 	MSN_SB_ERROR_AUTHFAILED, /**< Authentication failed joining the switchboard session */
    50 	MSN_SB_ERROR_UNKNOWN /**< An unknown error occurred. */
    51 
    52 } MsnSBErrorType;
    53 
    54 /**
    55  * A switchboard flag.
    56  */
    57 typedef enum
    58 {
    59 	MSN_SB_FLAG_IM = 0x01, /**< This switchboard is being used for a conversation. */
    60 	MSN_SB_FLAG_FT = 0x02  /**< This switchboard is being used for file transfer. */
    61 
    62 } MsnSBFlag;
    63 
    64 /**
    65  * A switchboard.
    66  *
    67  * A place where a bunch of users send messages to the rest of the users.
    68  */
    69 struct _MsnSwitchBoard
    70 {
    71 	MsnSession *session;   /**< Our parent session. */
    72 	MsnServConn *servconn; /**< The physical connection for this switchboard. */
    73 	MsnCmdProc *cmdproc;   /**< Convenience variable for servconn->cmdproc. */
    74 	char *im_user;
    75 
    76 	MsnSBFlag flag;
    77 	char *auth_key;
    78 	char *session_id;
    79 
    80 	PurpleConversation *conv; /**< The conversation that displays the
    81 							  messages of this switchboard, or @c NULL if
    82 							  this is a helper switchboard. */
    83 
    84 	gboolean empty;			/**< A flag that states if the swithcboard has no
    85 							  users in it. */
    86 	gboolean invited;		/**< A flag that states if we were invited to the
    87 							  switchboard. */
    88 	gboolean ready;			/**< A flag that states if this switchboard is
    89 							  ready to be used. */
    90 	gboolean closed;		/**< A flag that states if the switchboard has
    91 							  been closed by the user. */
    92 	gboolean destroying;	/**< A flag that states if the switchboard is
    93 							  alredy on the process of destruction. */
    94 
    95 	int current_users;
    96 	int total_users;
    97 	GList *users;
    98 
    99 	int chat_id;
   100 
   101 	GQueue *msg_queue; /**< Queue of messages to send. */
   102 	GList *ack_list; /**< List of messages waiting for an ack. */
   103 
   104 	MsnSBErrorType error; /**< The error that occurred in this switchboard
   105 							(if applicable). */
   106 	GList *slplinks; /**< The list of slplinks that are using this switchboard. */
   107 	guint reconn_timeout_h;
   108 };
   109 
   110 /**
   111  * Initialize the variables for switchboard creation.
   112  */
   113 void msn_switchboard_init(void);
   114 
   115 /**
   116  * Destroy the variables for switchboard creation.
   117  */
   118 void msn_switchboard_end(void);
   119 
   120 /**
   121  * Creates a new switchboard.
   122  *
   123  * @param session The MSN session.
   124  *
   125  * @return The new switchboard.
   126  */
   127 MsnSwitchBoard *msn_switchboard_new(MsnSession *session);
   128 
   129 /**
   130  * Destroys a switchboard.
   131  *
   132  * @param swboard The switchboard to destroy.
   133  */
   134 void msn_switchboard_destroy(MsnSwitchBoard *swboard);
   135 
   136 /**
   137  * Sets the auth key the switchboard must use when connecting.
   138  *
   139  * @param swboard The switchboard.
   140  * @param key     The auth key.
   141  */
   142 void msn_switchboard_set_auth_key(MsnSwitchBoard *swboard, const char *key);
   143 
   144 /**
   145  * Returns the auth key the switchboard must use when connecting.
   146  *
   147  * @param swboard The switchboard.
   148  *
   149  * @return The auth key.
   150  */
   151 const char *msn_switchboard_get_auth_key(MsnSwitchBoard *swboard);
   152 
   153 /**
   154  * Sets the session ID the switchboard must use when connecting.
   155  *
   156  * @param swboard The switchboard.
   157  * @param id      The session ID.
   158  */
   159 void msn_switchboard_set_session_id(MsnSwitchBoard *swboard, const char *id);
   160 
   161 /**
   162  * Returns the session ID the switchboard must use when connecting.
   163  *
   164  * @param swboard The switchboard.
   165  *
   166  * @return The session ID.
   167  */
   168 const char *msn_switchboard_get_session_id(MsnSwitchBoard *swboard);
   169 
   170 /**
   171  * Returns the next chat ID for use by a switchboard.
   172  *
   173  * @return The chat ID.
   174  */
   175 int msn_switchboard_get_chat_id(void);
   176 
   177 /**
   178  * Sets whether or not we were invited to this switchboard.
   179  *
   180  * @param swboard The switchboard.
   181  * @param invite  @c TRUE if invited, @c FALSE otherwise.
   182  */
   183 void msn_switchboard_set_invited(MsnSwitchBoard *swboard, gboolean invited);
   184 
   185 /**
   186  * Returns whether or not we were invited to this switchboard.
   187  *
   188  * @param swboard The switchboard.
   189  *
   190  * @return @c TRUE if invited, @c FALSE otherwise.
   191  */
   192 gboolean msn_switchboard_is_invited(MsnSwitchBoard *swboard);
   193 
   194 /**
   195  * Connects to a switchboard.
   196  *
   197  * @param swboard The switchboard.
   198  * @param host    The switchboard server host.
   199  * @param port    The switcbharod server port.
   200  *
   201  * @return @c TRUE if able to connect, or @c FALSE otherwise.
   202  */
   203 gboolean msn_switchboard_connect(MsnSwitchBoard *swboard,
   204 								 const char *host, int port);
   205 
   206 /**
   207  * Disconnects from a switchboard.
   208  *
   209  * @param swboard The switchboard to disconnect from.
   210  */
   211 void msn_switchboard_disconnect(MsnSwitchBoard *swboard);
   212 
   213 /**
   214  * Closes the switchboard.
   215  *
   216  * Called when a conversation is closed.
   217  *
   218  * @param swboard The switchboard to close.
   219  */
   220 void msn_switchboard_close(MsnSwitchBoard *swboard);
   221 
   222 /**
   223  * Release a switchboard from a certain function.
   224  *
   225  * @param swboard The switchboard to release.
   226  * @param flag The flag that states the function.
   227  */
   228 void msn_switchboard_release(MsnSwitchBoard *swboard, MsnSBFlag flag);
   229 
   230 /**
   231  * Returns whether or not we currently can send a message through this
   232  * switchboard.
   233  *
   234  * @param swboard The switchboard.
   235  *
   236  * @return @c TRUE if a message can be sent, @c FALSE otherwise.
   237  */
   238 gboolean msn_switchboard_can_send(MsnSwitchBoard *swboard);
   239 
   240 /**
   241  * Sends a message through this switchboard.
   242  *
   243  * @param swboard The switchboard.
   244  * @param msg The message.
   245  * @param queue A flag that states if we want this message to be queued (in
   246  * the case it cannot currently be sent).
   247  *
   248  * @return @c TRUE if a message can be sent, @c FALSE otherwise.
   249  */
   250 void msn_switchboard_send_msg(MsnSwitchBoard *swboard, MsnMessage *msg,
   251 							  gboolean queue);
   252 
   253 gboolean msn_switchboard_chat_leave(MsnSwitchBoard *swboard);
   254 gboolean msn_switchboard_chat_invite(MsnSwitchBoard *swboard, const char *who);
   255 
   256 void msn_switchboard_request(MsnSwitchBoard *swboard);
   257 void msn_switchboard_request_add_user(MsnSwitchBoard *swboard, const char *user);
   258 
   259 /**
   260  * Processes peer to peer messages.
   261  *
   262  * @param cmdproc The command processor.
   263  * @param msg     The message.
   264  */
   265 void msn_p2p_msg(MsnCmdProc *cmdproc, MsnMessage *msg);
   266 
   267 /**
   268  * Processes emoticon messages.
   269  *
   270  * @param cmdproc The command processor.
   271  * @param msg     The message.
   272  */
   273 void msn_emoticon_msg(MsnCmdProc *cmdproc, MsnMessage *msg);
   274 
   275 /**
   276  * Processes INVITE messages.
   277  *
   278  * @param cmdproc The command processor.
   279  * @param msg     The message.
   280  */
   281 void msn_invite_msg(MsnCmdProc *cmdproc, MsnMessage *msg);
   282 
   283 /**
   284  * Shows an ink message from this switchboard.
   285  *
   286  * @param swboard  The switchboard.
   287  * @param passport The user that sent the ink.
   288  * @param data     The ink data.
   289  */
   290 void msn_switchboard_show_ink(MsnSwitchBoard *swboard, const char *passport,
   291                               const char *data);
   292 
   293 #endif /* _MSN_SWITCHBOARD_H_ */
adium-1.4