Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/user.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     1 /**
       
     2  * @file user.h User 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_USER_H
       
    25 #define MSN_USER_H
       
    26 
       
    27 typedef struct _MsnUser  MsnUser;
       
    28 
       
    29 typedef enum
       
    30 {
       
    31 	MSN_NETWORK_UNKNOWN      = 0,
       
    32 	MSN_NETWORK_PASSPORT     = 1,
       
    33 	MSN_NETWORK_COMMUNICATOR = 2,
       
    34 	MSN_NETWORK_MOBILE       = 4,
       
    35 	MSN_NETWORK_MNI          = 8,
       
    36 	MSN_NETWORK_CIRCLE       = 9,
       
    37 	MSN_NETWORK_TEMP_GROUP   = 10,
       
    38 	MSN_NETWORK_CID          = 11,
       
    39 	MSN_NETWORK_CONNECT      = 13,
       
    40 	MSN_NETWORK_REMOTE       = 14,
       
    41 	MSN_NETWORK_SMTP         = 16,
       
    42 	MSN_NETWORK_YAHOO        = 32
       
    43 } MsnNetwork;
       
    44 
       
    45 /**
       
    46  * Current media.
       
    47  */
       
    48 typedef enum
       
    49 {
       
    50 	CURRENT_MEDIA_UNKNOWN,
       
    51 	CURRENT_MEDIA_MUSIC,
       
    52 	CURRENT_MEDIA_GAMES,
       
    53 	CURRENT_MEDIA_OFFICE
       
    54 } CurrentMediaType;
       
    55 
       
    56 #include "object.h"
       
    57 #include "session.h"
       
    58 #include "userlist.h"
       
    59 
       
    60 /**
       
    61  * Contains optional info about a user that is fairly uncommon.  We
       
    62  * put this info in in a separate struct to save memory because we
       
    63  * allocate an MsnUser struct for each buddy, but we generally only
       
    64  * need this information for a small percentage of our buddies
       
    65  * (usually less than 1%).  Putting it in a separate struct makes
       
    66  * MsnUser smaller by the size of a few pointers.
       
    67  */
       
    68 typedef struct _MsnUserExtendedInfo
       
    69 {
       
    70 	CurrentMediaType media_type; /**< Type of the user's current media.   */
       
    71 	char *media_title;  /**< Title of the user's current media.  */
       
    72 	char *media_artist; /**< Artist of the user's current media. */
       
    73 	char *media_album;  /**< Album of the user's current media.  */
       
    74 
       
    75 	char *phone_home;   /**< E.T. uses this.                     */
       
    76 	char *phone_work;   /**< Work phone number.                  */
       
    77 	char *phone_mobile; /**< Mobile phone number.                */
       
    78 } MsnUserExtendedInfo;
       
    79 
       
    80 /**
       
    81  * A user.
       
    82  */
       
    83 struct _MsnUser
       
    84 {
       
    85 	MsnUserList *userlist;
       
    86 
       
    87 	guint8 refcount;        /**< The reference count of this object */
       
    88 
       
    89 	char *passport;         /**< The passport account.          */
       
    90 	char *friendly_name;    /**< The friendly name.             */
       
    91 
       
    92 	char *uid;              /*< User ID                         */
       
    93 	GSList *endpoints;      /*< Endpoint-specific data          */
       
    94 
       
    95 	const char *status;     /**< The state of the user.         */
       
    96 	char *statusline;       /**< The state of the user.         */
       
    97 
       
    98 	gboolean idle;          /**< The idle state of the user.    */
       
    99 
       
   100 	MsnUserExtendedInfo *extinfo; /**< Extended info for the user. */
       
   101 
       
   102 	gboolean authorized;    /**< Authorized to add this user.   */
       
   103 	gboolean mobile;        /**< Signed up with MSN Mobile.     */
       
   104 
       
   105 	GList *group_ids;       /**< The group IDs.                 */
       
   106 	char *pending_group;    /**< A pending group to add.        */
       
   107 
       
   108 	MsnObject *msnobj;      /**< The user's MSN Object.         */
       
   109 
       
   110 	GHashTable *clientcaps; /**< The client's capabilities.     */
       
   111 
       
   112 	guint clientid;         /**< The client's ID                */
       
   113 	guint extcaps;			/**< The client's extended capabilities */
       
   114 
       
   115 	MsnNetwork networkid;   /**< The user's network             */
       
   116 
       
   117 	MsnListOp list_op;      /**< Which lists the user is in     */
       
   118 
       
   119 	/**
       
   120 	 * The membershipId for this buddy on our pending list.  Sent by
       
   121 	 * the contact's server
       
   122 	 */
       
   123 	guint member_id_on_pending_list;
       
   124 
       
   125 	char *invite_message;   /**< Invite message of user request */
       
   126 };
       
   127 
       
   128 /**
       
   129  * A specific user endpoint.
       
   130  */
       
   131 typedef struct MsnUserEndpoint {
       
   132 	char *id;               /**< The client's endpoint ID          */
       
   133 	char *name;             /**< The client's endpoint's name      */
       
   134 	int type;               /**< The client's endpoint type        */
       
   135 	guint clientid;         /**< The client's ID                   */
       
   136 	guint extcaps;          /**< The client's extended capabilites */
       
   137 
       
   138 } MsnUserEndpoint;
       
   139 
       
   140 /**************************************************************************
       
   141  ** @name User API                                                        *
       
   142  **************************************************************************/
       
   143 /*@{*/
       
   144 
       
   145 /**
       
   146  * Creates a new user structure.
       
   147  *
       
   148  * @param session      The MSN session.
       
   149  * @param passport     The initial passport.
       
   150  * @param stored_name  The initial stored name.
       
   151  *
       
   152  * @return A new user structure.  It will have a reference count of 1.
       
   153  */
       
   154 MsnUser *msn_user_new(MsnUserList *userlist, const char *passport,
       
   155 					  const char *friendly_name);
       
   156 
       
   157 /**
       
   158  * Increment the reference count.
       
   159  *
       
   160  * @param user 	The user.
       
   161  *
       
   162  * @return 		user.
       
   163  */
       
   164 MsnUser *msn_user_ref(MsnUser *user);
       
   165 
       
   166 /**
       
   167  * Decrement the reference count.  When the count reaches 0 the object is
       
   168  * automatically freed.
       
   169  *
       
   170  * @param user 	The user
       
   171  */
       
   172 void msn_user_unref(MsnUser *user);
       
   173 
       
   174 /**
       
   175  * Updates the user.
       
   176  *
       
   177  * Communicates with the core to update the ui, etc.
       
   178  *
       
   179  * @param user The user to update.
       
   180  */
       
   181 void msn_user_update(MsnUser *user);
       
   182 
       
   183  /**
       
   184   *  Sets the new statusline of user.
       
   185   *
       
   186   *  @param user The user.
       
   187   *  @param state The statusline string.
       
   188   */
       
   189 void msn_user_set_statusline(MsnUser *user, const char *statusline);
       
   190 
       
   191 /**
       
   192  * Sets the new state of user.
       
   193  *
       
   194  * @param user The user.
       
   195  * @param state The state string.
       
   196  */
       
   197 void msn_user_set_state(MsnUser *user, const char *state);
       
   198 
       
   199 /**
       
   200  * Sets the passport account for a user.
       
   201  *
       
   202  * @param user     The user.
       
   203  * @param passport The passport account.
       
   204  */
       
   205 void msn_user_set_passport(MsnUser *user, const char *passport);
       
   206 
       
   207 /**
       
   208  * Sets the friendly name for a user.
       
   209  *
       
   210  * @param user The user.
       
   211  * @param name The friendly name.
       
   212  *
       
   213  * @returns TRUE is name actually changed, FALSE otherwise.
       
   214  */
       
   215 gboolean msn_user_set_friendly_name(MsnUser *user, const char *name);
       
   216 
       
   217 /**
       
   218  * Sets the buddy icon for a local user.
       
   219  *
       
   220  * @param user     The user.
       
   221  * @param img      The buddy icon image
       
   222  */
       
   223 void msn_user_set_buddy_icon(MsnUser *user, PurpleStoredImage *img);
       
   224 
       
   225 /**
       
   226  * Sets the group ID list for a user.
       
   227  *
       
   228  * @param user The user.
       
   229  * @param ids  The group ID list.
       
   230  */
       
   231 void msn_user_set_group_ids(MsnUser *user, GList *ids);
       
   232 
       
   233 /**
       
   234  * Adds the group ID for a user.
       
   235  *
       
   236  * @param user The user.
       
   237  * @param id   The group ID.
       
   238  */
       
   239 void msn_user_add_group_id(MsnUser *user, const char * id);
       
   240 
       
   241 /**
       
   242  * Removes the group ID from a user.
       
   243  *
       
   244  * @param user The user.
       
   245  * @param id   The group ID.
       
   246  */
       
   247 void msn_user_remove_group_id(MsnUser *user, const char * id);
       
   248 
       
   249 /**
       
   250  * Sets the pending group for a user.
       
   251  *
       
   252  * @param user  The user.
       
   253  * @param group The group name.
       
   254  */
       
   255 void msn_user_set_pending_group(MsnUser *user, const char *group);
       
   256 
       
   257 /**
       
   258  * Removes the pending group from a user.
       
   259  *
       
   260  * @param user The user.
       
   261  *
       
   262  * @return Returns the pending group name.
       
   263  */
       
   264 char *msn_user_remove_pending_group(MsnUser *user);
       
   265 
       
   266 /**
       
   267  * Sets the home phone number for a user.
       
   268  *
       
   269  * @param user   The user.
       
   270  * @param number The home phone number.
       
   271  */
       
   272 void msn_user_set_home_phone(MsnUser *user, const char *number);
       
   273 
       
   274 /**
       
   275  * Sets the work phone number for a user.
       
   276  *
       
   277  * @param user   The user.
       
   278  * @param number The work phone number.
       
   279  */
       
   280 void msn_user_set_work_phone(MsnUser *user, const char *number);
       
   281 
       
   282 void msn_user_set_uid(MsnUser *user, const char *uid);
       
   283 
       
   284 /**
       
   285  * Sets endpoint data for a user.
       
   286  *
       
   287  * @param user     The user.
       
   288  * @param endpoint The endpoint.
       
   289  * @param data     The endpoint data.
       
   290  */
       
   291 void
       
   292 msn_user_set_endpoint_data(MsnUser *user, const char *endpoint, MsnUserEndpoint *data);
       
   293 
       
   294 /**
       
   295  * Clears all endpoint data for a user.
       
   296  *
       
   297  * @param user     The user.
       
   298  */
       
   299 void
       
   300 msn_user_clear_endpoints(MsnUser *user);
       
   301 
       
   302 /**
       
   303  * Sets the client id for a user.
       
   304  *
       
   305  * @param user     The user.
       
   306  * @param clientid The client id.
       
   307  */
       
   308 void msn_user_set_clientid(MsnUser *user, guint clientid);
       
   309 
       
   310 /**
       
   311  * Sets the client id for a user.
       
   312  *
       
   313  * @param user     The user.
       
   314  * @param extcaps  The client's extended capabilities.
       
   315  */
       
   316 void msn_user_set_extcaps(MsnUser *user, guint extcaps);
       
   317 
       
   318 /**
       
   319  * Sets the network id for a user.
       
   320  *
       
   321  * @param user    The user.
       
   322  * @param network The network id.
       
   323  */
       
   324 void msn_user_set_network(MsnUser *user, MsnNetwork network);
       
   325 
       
   326 /**
       
   327  * Sets the mobile phone number for a user.
       
   328  *
       
   329  * @param user   The user.
       
   330  * @param number The mobile phone number.
       
   331  */
       
   332 void msn_user_set_mobile_phone(MsnUser *user, const char *number);
       
   333 
       
   334 /**
       
   335  * Sets the MSNObject for a user.
       
   336  *
       
   337  * @param user The user.
       
   338  * @param obj  The MSNObject.
       
   339  */
       
   340 void msn_user_set_object(MsnUser *user, MsnObject *obj);
       
   341 
       
   342 /**
       
   343  * Sets the client information for a user.
       
   344  *
       
   345  * @param user The user.
       
   346  * @param info The client information.
       
   347  */
       
   348 void msn_user_set_client_caps(MsnUser *user, GHashTable *info);
       
   349 
       
   350 /**
       
   351  * Sets the invite message for a user.
       
   352  *
       
   353  * @param user    The user.
       
   354  * @param message The invite message for a user.
       
   355  */
       
   356 void msn_user_set_invite_message(MsnUser *user, const char *message);
       
   357 
       
   358 
       
   359 /**
       
   360  * Returns the passport account for a user.
       
   361  *
       
   362  * @param user The user.
       
   363  *
       
   364  * @return The passport account.
       
   365  */
       
   366 const char *msn_user_get_passport(const MsnUser *user);
       
   367 
       
   368 /**
       
   369  * Returns the friendly name for a user.
       
   370  *
       
   371  * @param user The user.
       
   372  *
       
   373  * @return The friendly name.
       
   374  */
       
   375 const char *msn_user_get_friendly_name(const MsnUser *user);
       
   376 
       
   377 /**
       
   378  * Returns the home phone number for a user.
       
   379  *
       
   380  * @param user The user.
       
   381  *
       
   382  * @return The user's home phone number.
       
   383  */
       
   384 const char *msn_user_get_home_phone(const MsnUser *user);
       
   385 
       
   386 /**
       
   387  * Returns the work phone number for a user.
       
   388  *
       
   389  * @param user The user.
       
   390  *
       
   391  * @return The user's work phone number.
       
   392  */
       
   393 const char *msn_user_get_work_phone(const MsnUser *user);
       
   394 
       
   395 /**
       
   396  * Returns the mobile phone number for a user.
       
   397  *
       
   398  * @param user The user.
       
   399  *
       
   400  * @return The user's mobile phone number.
       
   401  */
       
   402 const char *msn_user_get_mobile_phone(const MsnUser *user);
       
   403 
       
   404 /**
       
   405  * Gets endpoint data for a user.
       
   406  *
       
   407  * @param user     The user.
       
   408  * @param endpoint The endpoint.
       
   409  *
       
   410  * @return The user's endpoint data.
       
   411  */
       
   412 MsnUserEndpoint *
       
   413 msn_user_get_endpoint_data(MsnUser *user, const char *endpoint);
       
   414 
       
   415 /**
       
   416  * Returns the client id for a user.
       
   417  *
       
   418  * @param user    The user.
       
   419  *
       
   420  * @return The user's client id.
       
   421  */
       
   422 guint msn_user_get_clientid(const MsnUser *user);
       
   423 
       
   424 /**
       
   425  * Returns the extended capabilities for a user.
       
   426  *
       
   427  * @param user    The user.
       
   428  *
       
   429  * @return The user's extended capabilities.
       
   430  */
       
   431 guint msn_user_get_extcaps(const MsnUser *user);
       
   432 
       
   433 /**************************************************************************
       
   434  * Utility functions
       
   435  **************************************************************************/
       
   436 
       
   437 
       
   438 /**
       
   439  * Check if the user is part of the group.
       
   440  *
       
   441  * @param user 		The user we are asking group membership.
       
   442  * @param group_id 	The group where the user may be in.
       
   443  *
       
   444  * @return TRUE if user is part of the group. Otherwise, FALSE.
       
   445  */
       
   446 gboolean msn_user_is_in_group(MsnUser *user, const char * group_id);
       
   447 
       
   448 /**
       
   449  * Check if user is on list.
       
   450  *
       
   451  * @param user 		The user we are asking list membership.
       
   452  * @param list_id 	The list where the user may be in.
       
   453  *
       
   454  * @return TRUE if the user is on the list, else FALSE.
       
   455  */
       
   456 gboolean msn_user_is_in_list(MsnUser *user, MsnListId list_id);
       
   457 /**
       
   458  * Returns the network id for a user.
       
   459  *
       
   460  * @param user    The user.
       
   461  *
       
   462  * @return The user's network id.
       
   463  */
       
   464 MsnNetwork msn_user_get_network(const MsnUser *user);
       
   465 
       
   466 /**
       
   467  * Returns the MSNObject for a user.
       
   468  *
       
   469  * @param user The user.
       
   470  *
       
   471  * @return The MSNObject.
       
   472  */
       
   473 MsnObject *msn_user_get_object(const MsnUser *user);
       
   474 
       
   475 /**
       
   476  * Returns the client information for a user.
       
   477  *
       
   478  * @param user The user.
       
   479  *
       
   480  * @return The client information.
       
   481  */
       
   482 GHashTable *msn_user_get_client_caps(const MsnUser *user);
       
   483 
       
   484 /**
       
   485  * Returns the invite message for a user.
       
   486  *
       
   487  * @param user The user.
       
   488  *
       
   489  * @return The user's invite message.
       
   490  */
       
   491 const char *msn_user_get_invite_message(const MsnUser *user);
       
   492 
       
   493 /**
       
   494  * check to see if user is online
       
   495  */
       
   496 gboolean msn_user_is_online(PurpleAccount *account, const char *name);
       
   497 
       
   498 /**
       
   499  * check to see if user is Yahoo User
       
   500  */
       
   501 gboolean msn_user_is_yahoo(PurpleAccount *account, const char *name);
       
   502 
       
   503 void msn_user_set_op(MsnUser *user, MsnListOp list_op);
       
   504 void msn_user_unset_op(MsnUser *user, MsnListOp list_op);
       
   505 
       
   506 /**
       
   507  * Compare the given passport with the one of the user
       
   508  *
       
   509  * @param user 	User to compare.
       
   510  * @oaran passport 	Passport to compare.
       
   511  *
       
   512  * @return Zero if the passport match with the one of the user, otherwise
       
   513  * a positive integer if the user passport is greather than the one given
       
   514  * and a negative integer if it is less.
       
   515  */
       
   516 int msn_user_passport_cmp(MsnUser *user, const char *passport);
       
   517 
       
   518 /**
       
   519  * Checks whether a user is capable of some task.
       
   520  *
       
   521  * @param user       The user.
       
   522  * @param endpoint   The endpoint. Can be @NULL to check overall capabilities.
       
   523  * @param capability The capability (including client version).
       
   524  * @param extcap     The extended capability.
       
   525  *
       
   526  * @return Whether the user supports the capability.
       
   527  */
       
   528 gboolean
       
   529 msn_user_is_capable(MsnUser *user, char *endpoint, guint capability, guint extcap);
       
   530 
       
   531 /*@}*/
       
   532 
       
   533 #endif /* MSN_USER_H */