Mercurial > pidgin
changeset 21869:a92574a57460
Documentation tweaks and more g_return_if_fail checks for NULL parameters which
shouldn't be.
| author | Will Thompson <will.thompson@collabora.co.uk> |
|---|---|
| date | Tue, 18 Dec 2007 16:02:35 +0000 |
| parents | e5208b29d807 |
| children | 9398f5032d83 |
| files | libpurple/request.c libpurple/request.h |
| diffstat | 2 files changed, 256 insertions(+), 179 deletions(-) [+] |
line wrap: on
line diff
--- a/libpurple/request.c Tue Dec 18 11:05:40 2007 +0000 +++ b/libpurple/request.c Tue Dec 18 16:02:35 2007 +0000 @@ -1208,6 +1208,8 @@ g_return_val_if_fail(ok_text != NULL, NULL); g_return_val_if_fail(ok_cb != NULL, NULL); + g_return_val_if_fail(cancel_text != NULL, NULL); + g_return_val_if_fail(cancel_cb != NULL, NULL); ops = purple_request_get_ui_ops(); @@ -1296,6 +1298,8 @@ g_return_val_if_fail(fields != NULL, NULL); g_return_val_if_fail(ok_text != NULL, NULL); g_return_val_if_fail(ok_cb != NULL, NULL); + g_return_val_if_fail(cancel_text != NULL, NULL); + g_return_val_if_fail(cancel_cb != NULL, NULL); ops = purple_request_get_ui_ops();
--- a/libpurple/request.h Tue Dec 18 11:05:40 2007 +0000 +++ b/libpurple/request.h Tue Dec 18 16:02:35 2007 +0000 @@ -183,39 +183,53 @@ */ typedef struct { + /** @see purple_request_input(). */ void *(*request_input)(const char *title, const char *primary, - const char *secondary, const char *default_value, - gboolean multiline, gboolean masked, gchar *hint, - const char *ok_text, GCallback ok_cb, - const char *cancel_text, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data); + const char *secondary, const char *default_value, + gboolean multiline, gboolean masked, gchar *hint, + const char *ok_text, GCallback ok_cb, + const char *cancel_text, GCallback cancel_cb, + PurpleAccount *account, const char *who, + PurpleConversation *conv, void *user_data); + + /** @see purple_request_choice_varg(). */ void *(*request_choice)(const char *title, const char *primary, - const char *secondary, int default_value, - const char *ok_text, GCallback ok_cb, - const char *cancel_text, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data, va_list choices); + const char *secondary, int default_value, + const char *ok_text, GCallback ok_cb, + const char *cancel_text, GCallback cancel_cb, + PurpleAccount *account, const char *who, + PurpleConversation *conv, void *user_data, + va_list choices); + + /** @see purple_request_action_varg(). */ void *(*request_action)(const char *title, const char *primary, - const char *secondary, int default_action, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data, size_t action_count, - va_list actions); + const char *secondary, int default_action, + PurpleAccount *account, const char *who, + PurpleConversation *conv, void *user_data, + size_t action_count, va_list actions); + + /** @see purple_request_fields(). */ void *(*request_fields)(const char *title, const char *primary, - const char *secondary, PurpleRequestFields *fields, - const char *ok_text, GCallback ok_cb, - const char *cancel_text, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data); + const char *secondary, PurpleRequestFields *fields, + const char *ok_text, GCallback ok_cb, + const char *cancel_text, GCallback cancel_cb, + PurpleAccount *account, const char *who, + PurpleConversation *conv, void *user_data); + + /** @see purple_request_file(). */ void *(*request_file)(const char *title, const char *filename, - gboolean savedialog, GCallback ok_cb, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data); + gboolean savedialog, GCallback ok_cb, + GCallback cancel_cb, PurpleAccount *account, + const char *who, PurpleConversation *conv, + void *user_data); + void (*close_request)(PurpleRequestType type, void *ui_handle); + + /** @see purple_request_folder(). */ void *(*request_folder)(const char *title, const char *dirname, - GCallback ok_cb, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data); + GCallback ok_cb, GCallback cancel_cb, + PurpleAccount *account, const char *who, + PurpleConversation *conv, void *user_data); void (*_purple_reserved1)(void); void (*_purple_reserved2)(void); @@ -1159,198 +1173,247 @@ * Prompts the user for text input. * * @param handle The plugin or connection handle. For some - * things this is EXTREMELY important. The - * handle is used to programmatically close - * the request dialog when it is no longer - * needed. For PRPLs this is often a pointer - * to the PurpleConnection instance. For plugins - * this should be a similar, unique memory - * location. This value is important because - * it allows a request to be closed, say, when - * you sign offline. If the request is NOT - * closed it is VERY likely to cause a crash - * whenever the callback handler functions are - * triggered. - * @param title The title of the message. - * @param primary The main point of the message. - * @param secondary The secondary information. + * things this is <em>extremely</em> important. The + * handle is used to programmatically close the request + * dialog when it is no longer needed. For PRPLs this + * is often a pointer to the #PurpleConnection + * instance. For plugins this should be a similar, + * unique memory location. This value is important + * because it allows a request to be closed with + * purple_request_close_with_handle() when, for + * example, you sign offline. If the request is + * <em>not</em> closed it is <strong>very</strong> + * likely to cause a crash whenever the callback + * handler functions are triggered. + * @param title The title of the message, or @c NULL if it should have + * no title. + * @param primary The main point of the message, or @c NULL if you're + * feeling enigmatic. + * @param secondary Secondary information, or @c NULL if there is none. * @param default_value The default value. - * @param multiline TRUE if the inputted text can span multiple lines. - * @param masked TRUE if the inputted text should be masked in some way. + * @param multiline @c TRUE if the inputted text can span multiple lines. + * @param masked @c TRUE if the inputted text should be masked in some + * way (such as by displaying characters as stars). This + * might be because the input is some kind of password. * @param hint Optionally suggest how the input box should appear. - * Use "html," for example, to allow the user to enter + * Use "html", for example, to allow the user to enter * HTML. - * @param ok_text The text for the @c OK button. - * @param ok_cb The callback for the @c OK button. - * @param cancel_text The text for the @c Cancel button. - * @param cancel_cb The callback for the @c Cancel button. - * @param account The PurpleAccount associated with this request, or NULL if none is - * @param who The username of the buddy assocaited with this request, or NULL if none is - * @param conv The PurpleConversation associated with this request, or NULL if none is + * @param ok_text The text for the @c OK button, which may not be @c NULL. + * @param ok_cb The callback for the @c OK button, which may not be @c + * NULL. + * @param cancel_text The text for the @c Cancel button, which may not be @c + * NULL. + * @param cancel_cb The callback for the @c Cancel button, which may not be + * @c NULL. + * @param account The #PurpleAccount associated with this request, or @c + * NULL if none is. + * @param who The username of the buddy assonciated with this request, + * or @c NULL if none is. + * @param conv The #PurpleConversation associated with this request, or + * @c NULL if none is. * @param user_data The data to pass to the callback. * * @return A UI-specific handle. */ -void *purple_request_input(void *handle, const char *title, - const char *primary, const char *secondary, - const char *default_value, - gboolean multiline, gboolean masked, gchar *hint, - const char *ok_text, GCallback ok_cb, - const char *cancel_text, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data); +void *purple_request_input(void *handle, const char *title, const char *primary, + const char *secondary, const char *default_value, gboolean multiline, + gboolean masked, gchar *hint, + const char *ok_text, GCallback ok_cb, + const char *cancel_text, GCallback cancel_cb, + PurpleAccount *account, const char *who, PurpleConversation *conv, + void *user_data); /** * Prompts the user for multiple-choice input. * - * @param handle The plugin or connection handle. For some - * things this is EXTREMELY important. See - * the comments on purple_request_input. - * @param title The title of the message. - * @param primary The main point of the message. - * @param secondary The secondary information. - * @param default_value The default value. - * @param ok_text The text for the @c OK button. - * @param ok_cb The callback for the @c OK button. - * @param cancel_text The text for the @c Cancel button. - * @param cancel_cb The callback for the @c Cancel button. - * @param account The PurpleAccount associated with this request, or NULL if none is - * @param who The username of the buddy assocaited with this request, or NULL if none is - * @param conv The PurpleConversation associated with this request, or NULL if none is + * @param handle The plugin or connection handle. For some things this + * is <em>extremely</em> important. See the comments on + * purple_request_input(). + * @param title The title of the message, or @c NULL if it should have + * no title. + * @param primary The main point of the message, or @c NULL if you're + * feeling enigmatic. + * @param secondary Secondary information, or @c NULL if there is none. + * @param default_value The default choice; this should be one of the values + * listed in the varargs. + * @param ok_text The text for the @c OK button, which may not be @c NULL. + * @param ok_cb The callback for the @c OK button, which may not be @c + * NULL. + * @param cancel_text The text for the @c Cancel button, which may not be @c + * NULL. + * @param cancel_cb The callback for the @c Cancel button, which may not be + * @c NULL. + * @param account The #PurpleAccount associated with this request, or @c + * NULL if none is. + * @param who The username of the buddy assonciated with this request, + * or @c NULL if none is. + * @param conv The #PurpleConversation associated with this request, or + * @c NULL if none is. * @param user_data The data to pass to the callback. - * @param ... The choices. This argument list should be - * terminated with a NULL parameter. + * @param ... The choices, which should be pairs of <tt>char *</tt> + * descriptions and <tt>int</tt> values, terminated with a + * @c NULL parameter. * * @return A UI-specific handle. */ -void *purple_request_choice(void *handle, const char *title, - const char *primary, const char *secondary, - int default_value, - const char *ok_text, GCallback ok_cb, - const char *cancel_text, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data, ...) G_GNUC_NULL_TERMINATED; +void *purple_request_choice(void *handle, const char *title, const char *primary, + const char *secondary, int default_value, + const char *ok_text, GCallback ok_cb, + const char *cancel_text, GCallback cancel_cb, + PurpleAccount *account, const char *who, PurpleConversation *conv, + void *user_data, ...) G_GNUC_NULL_TERMINATED; /** * Prompts the user for multiple-choice input. * - * @param handle The plugin or connection handle. For some - * things this is EXTREMELY important. See - * the comments on purple_request_input. - * @param title The title of the message. - * @param primary The main point of the message. - * @param secondary The secondary information. - * @param default_value The default value. - * @param ok_text The text for the @c OK button. - * @param ok_cb The callback for the @c OK button. - * @param cancel_text The text for the @c Cancel button. - * @param cancel_cb The callback for the @c Cancel button. - * @param account The PurpleAccount associated with this request, or NULL if none is - * @param who The username of the buddy assocaited with this request, or NULL if none is - * @param conv The PurpleConversation associated with this request, or NULL if none is + * @param handle The plugin or connection handle. For some things this + * is <em>extremely</em> important. See the comments on + * purple_request_input(). + * @param title The title of the message, or @c NULL if it should have + * no title. + * @param primary The main point of the message, or @c NULL if you're + * feeling enigmatic. + * @param secondary Secondary information, or @c NULL if there is none. + * @param default_value The default choice; this should be one of the values + * listed in the varargs. + * @param ok_text The text for the @c OK button, which may not be @c NULL. + * @param ok_cb The callback for the @c OK button, which may not be @c + * NULL. + * @param cancel_text The text for the @c Cancel button, which may not be @c + * NULL. + * @param cancel_cb The callback for the @c Cancel button, which may not be + * @c NULL. + * @param account The #PurpleAccount associated with this request, or @c + * NULL if none is + * @param who The username of the buddy assonciated with this request, + * or @c NULL if none is + * @param conv The #PurpleConversation associated with this request, or + * @c NULL if none is * @param user_data The data to pass to the callback. - * @param choices The choices. This argument list should be - * terminated with a @c NULL parameter. + * @param choices The choices, which should be pairs of <tt>char *</tt> + * descriptions and <tt>int</tt> values, terminated with a + * @c NULL parameter. * * @return A UI-specific handle. */ void *purple_request_choice_varg(void *handle, const char *title, - const char *primary, const char *secondary, - int default_value, - const char *ok_text, GCallback ok_cb, - const char *cancel_text, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data, va_list choices); + const char *primary, const char *secondary, int default_value, + const char *ok_text, GCallback ok_cb, + const char *cancel_text, GCallback cancel_cb, + PurpleAccount *account, const char *who, PurpleConversation *conv, + void *user_data, va_list choices); /** * Prompts the user for an action. * * This is often represented as a dialog with a button for each action. * - * @param handle The plugin or connection handle. For some - * things this is EXTREMELY important. See - * the comments on purple_request_input. - * @param title The title of the message. - * @param primary The main point of the message. - * @param secondary The secondary information. - * @param default_action The default value. - * @param account The PurpleAccount associated with this request, or NULL if none is - * @param who The username of the buddy assocaited with this request, or NULL if none is - * @param conv The PurpleConversation associated with this request, or NULL if none is + * @param handle The plugin or connection handle. For some things this + * is <em>extremely</em> important. See the comments on + * purple_request_input(). + * @param title The title of the message, or @c NULL if it should have + * no title. + * @param primary The main point of the message, or @c NULL if you're + * feeling enigmatic. + * @param secondary Secondary information, or @c NULL if there is none. + * @param default_action The default action, zero-indexed; if the third action + * supplied should be the default, supply <tt>2</tt>. + * @param account The #PurpleAccount associated with this request, or @c + * NULL if none is. + * @param who The username of the buddy assonciated with this request, + * or @c NULL if none is. + * @param conv The #PurpleConversation associated with this request, or + * @c NULL if none is. * @param user_data The data to pass to the callback. * @param action_count The number of actions. * @param ... A list of actions. These are pairs of * arguments. The first of each pair is the - * string that appears on the button. It should + * <tt>char *</tt> that appears on the button. It should * have an underscore before the letter you want * to use as the accelerator key for the button. - * The second of each pair is the callback + * The second of each pair is the <tt>GCallback</tt> * function to use when the button is clicked. * * @return A UI-specific handle. */ -void *purple_request_action(void *handle, const char *title, - const char *primary, const char *secondary, - int default_action, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data, size_t action_count, ...); +void *purple_request_action(void *handle, const char *title, const char *primary, + const char *secondary, int default_action, PurpleAccount *account, + const char *who, PurpleConversation *conv, void *user_data, + size_t action_count, ...); /** * Prompts the user for an action. * * This is often represented as a dialog with a button for each action. * - * @param handle The plugin or connection handle. For some - * things this is EXTREMELY important. See - * the comments on purple_request_input. - * @param title The title of the message. - * @param primary The main point of the message. - * @param secondary The secondary information. - * @param default_action The default value. - * @param account The PurpleAccount associated with this request, or NULL if none is - * @param who The username of the buddy assocaited with this request, or NULL if none is - * @param conv The PurpleConversation associated with this request, or NULL if none is + * @param handle The plugin or connection handle. For some things this + * is <em>extremely</em> important. See the comments on + * purple_request_input(). + * @param title The title of the message, or @c NULL if it should have + * no title. + * @param primary The main point of the message, or @c NULL if you're + * feeling enigmatic. + * @param secondary Secondary information, or @c NULL if there is none. + * @param default_action The default action, zero-indexed; if the third action + * supplied should be the default, supply <tt>2</tt>. + * @param account The #PurpleAccount associated with this request, or @c + * NULL if none is. + * @param who The username of the buddy assonciated with this request, + * or @c NULL if none is. + * @param conv The #PurpleConversation associated with this request, or + * @c NULL if none is. * @param user_data The data to pass to the callback. * @param action_count The number of actions. - * @param actions A list of actions and callbacks. + * @param actions A list of actions. These are pairs of + * arguments. The first of each pair is the + * <tt>char *</tt> that appears on the button. It should + * have an underscore before the letter you want + * to use as the accelerator key for the button. + * The second of each pair is the <tt>GCallback</tt> + * function to use when the button is clicked. * * @return A UI-specific handle. */ void *purple_request_action_varg(void *handle, const char *title, - const char *primary, const char *secondary, - int default_action, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data, size_t action_count, - va_list actions); + const char *primary, const char *secondary, int default_action, + PurpleAccount *account, const char *who, PurpleConversation *conv, + void *user_data, size_t action_count, va_list actions); /** * Displays groups of fields for the user to fill in. * - * @param handle The plugin or connection handle. For some - * things this is EXTREMELY important. See - * the comments on purple_request_input. - * @param title The title of the message. - * @param primary The main point of the message. - * @param secondary The secondary information. + * @param handle The plugin or connection handle. For some things this + * is <em>extremely</em> important. See the comments on + * purple_request_input(). + * @param title The title of the message, or @c NULL if it should have + * no title. + * @param primary The main point of the message, or @c NULL if you're + * feeling enigmatic. + * @param secondary Secondary information, or @c NULL if there is none. * @param fields The list of fields. - * @param ok_text The text for the @c OK button. - * @param ok_cb The callback for the @c OK button. - * @param cancel_text The text for the @c Cancel button. - * @param cancel_cb The callback for the @c Cancel button. - * @param account The PurpleAccount associated with this request, or NULL if none is - * @param who The username of the buddy associated with this request, or NULL if none is - * @param conv The PurpleConversation associated with this request, or NULL if none is + * @param ok_text The text for the @c OK button, which may not be @c NULL. + * @param ok_cb The callback for the @c OK button, which may not be @c + * NULL. + * @param cancel_text The text for the @c Cancel button, which may not be @c + * NULL. + * @param cancel_cb The callback for the @c Cancel button, which may not be + * @c NULL. + * @param account The #PurpleAccount associated with this request, or @c + * NULL if none is + * @param who The username of the buddy assonciated with this request, + * or @c NULL if none is + * @param conv The #PurpleConversation associated with this request, or + * @c NULL if none is * @param user_data The data to pass to the callback. * * @return A UI-specific handle. */ -void *purple_request_fields(void *handle, const char *title, - const char *primary, const char *secondary, - PurpleRequestFields *fields, - const char *ok_text, GCallback ok_cb, - const char *cancel_text, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data); +void *purple_request_fields(void *handle, const char *title, const char *primary, + const char *secondary, PurpleRequestFields *fields, + const char *ok_text, GCallback ok_cb, + const char *cancel_text, GCallback cancel_cb, + PurpleAccount *account, const char *who, PurpleConversation *conv, + void *user_data); /** * Closes a request. @@ -1363,7 +1426,10 @@ /** * Closes all requests registered with the specified handle. * - * @param handle The handle. + * @param handle The handle, as supplied as the @a handle parameter to one of the + * <tt>purple_request_*</tt> functions. + * + * @see purple_request_input(). */ void purple_request_close_with_handle(void *handle); @@ -1401,50 +1467,57 @@ * Displays a file selector request dialog. Returns the selected filename to * the callback. Can be used for either opening a file or saving a file. * - * @param handle The plugin or connection handle. For some - * things this is EXTREMELY important. See - * the comments on purple_request_input. - * @param title The title for the dialog (may be @c NULL) + * @param handle The plugin or connection handle. For some things this + * is <em>extremely</em> important. See the comments on + * purple_request_input(). + * @param title The title of the message, or @c NULL if it should have + * no title. * @param filename The default filename (may be @c NULL) * @param savedialog True if this dialog is being used to save a file. * False if it is being used to open a file. * @param ok_cb The callback for the @c OK button. * @param cancel_cb The callback for the @c Cancel button. - * @param account The PurpleAccount associated with this request, or NULL if none is - * @param who The username of the buddy assocaited with this request, or NULL if none is - * @param conv The PurpleConversation associated with this request, or NULL if none is + * @param account The #PurpleAccount associated with this request, or @c + * NULL if none is + * @param who The username of the buddy assonciated with this request, + * or @c NULL if none is + * @param conv The #PurpleConversation associated with this request, or + * @c NULL if none is * @param user_data The data to pass to the callback. * * @return A UI-specific handle. */ void *purple_request_file(void *handle, const char *title, const char *filename, - gboolean savedialog, - GCallback ok_cb, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data); + gboolean savedialog, GCallback ok_cb, GCallback cancel_cb, + PurpleAccount *account, const char *who, PurpleConversation *conv, + void *user_data); /** * Displays a folder select dialog. Returns the selected filename to * the callback. * - * @param handle The plugin or connection handle. For some - * things this is EXTREMELY important. See - * the comments on purple_request_input. - * @param title The title for the dialog (may be @c NULL) + * @param handle The plugin or connection handle. For some things this + * is <em>extremely</em> important. See the comments on + * purple_request_input(). + * @param title The title of the message, or @c NULL if it should have + * no title. * @param dirname The default directory name (may be @c NULL) * @param ok_cb The callback for the @c OK button. * @param cancel_cb The callback for the @c Cancel button. - * @param account The PurpleAccount associated with this request, or NULL if none is - * @param who The username of the buddy assocaited with this request, or NULL if none is - * @param conv The PurpleConversation associated with this request, or NULL if none is + * @param account The #PurpleAccount associated with this request, or @c + * NULL if none is + * @param who The username of the buddy assonciated with this request, + * or @c NULL if none is + * @param conv The #PurpleConversation associated with this request, or + * @c NULL if none is * @param user_data The data to pass to the callback. * * @return A UI-specific handle. */ void *purple_request_folder(void *handle, const char *title, const char *dirname, - GCallback ok_cb, GCallback cancel_cb, - PurpleAccount *account, const char *who, PurpleConversation *conv, - void *user_data); + GCallback ok_cb, GCallback cancel_cb, + PurpleAccount *account, const char *who, PurpleConversation *conv, + void *user_data); /*@}*/