| 98 | | /* The callback function for our /notify command. This function simply pops up |
| 99 | | * a notification with the word entered as the argument to the command */ |
| | 115 | /** |
| | 116 | * The callback function for our /notify command. This function simply pops up |
| | 117 | * a notification with the word entered as the argument to the command |
| | 118 | * |
| | 119 | * @param conv The conversation that the command occurred in |
| | 120 | * @param cmd The exact command that was entered |
| | 121 | * @param args The args that were passed with the command |
| | 122 | * @param error ?Any errors that occurred? |
| | 123 | * @param data Any special user-defined data that was assigned during |
| | 124 | * cmd_register |
| | 125 | */ |
| 113 | | |
| 114 | | |
| 115 | | |
| 116 | | /* As we've covered before, libpurple calls this function, if present, when it |
| 117 | | * loads the plugin. Here we're using it to show off the capabilities of the |
| 118 | | * debug API and just blindly returning TRUE to tell libpurple it's safe to |
| 119 | | * continue loading. */ |
| | 139 | /** |
| | 140 | * Because we added a pointer to this function in the load section of our |
| | 141 | * PurplePluginInfo, this function is called when the plugin loads. |
| | 142 | * Here we're using it to show off the capabilities of the |
| | 143 | * command API by registering a few commands. We return TRUE to tell libpurple |
| | 144 | * it's safe to continue loading. |
| | 145 | */ |
| 133 | | /* Register a command to allow a user to enter /log some message and have |
| 134 | | * that message stored to the log. This command runs with default priority, |
| 135 | | * can only be used in a standard chat message, not while in group chat |
| 136 | | * mode */ |
| 137 | | |
| | 159 | // Register a command to allow a user to enter /log some message and have |
| | 160 | // that message stored to the log. This command runs with default priority, |
| | 161 | // can only be used in a standard chat message, not while in group chat |
| | 162 | // mode |
| | 163 | log_command_id = purple_cmd_register |
| 139 | | "s", /* command arguments */ |
| 140 | | PURPLE_CMD_P_DEFAULT, /* command priority */ |
| 141 | | PURPLE_CMD_FLAG_IM, /* flags saying where |
| 142 | | command can be used */ |
| 143 | | |
| 144 | | NULL, /* We do not need to pass |
| 145 | | plugin ID */ |
| 146 | | |
| 147 | | log_cb, /* Name of the callback |
| 148 | | function */ |
| 149 | | log_help, |
| 150 | | |
| 151 | | NULL /* We do not need any special |
| 152 | | user defined data here */ |
| | 165 | "s", /* command argument format */ |
| | 166 | PURPLE_CMD_P_DEFAULT, /* command priority flags */ |
| | 167 | PURPLE_CMD_FLAG_IM, /* command usage flags */ |
| | 168 | PLUGIN_ID, /* Plugin ID */ |
| | 169 | log_cb, /* Name of the callback function */ |
| | 170 | log_help, /* Help message */ |
| | 171 | NULL /* Any special user-defined data */ |
| 159 | | |
| 160 | | /* Register a command to allow a user to enter /notify some word and have |
| 161 | | * that word notified back to them. This command runs with high priority, |
| 162 | | * can only be used both in group and standard chat messages */ |
| 163 | | purple_cmd_register |
| | 178 | // Register a command to allow a user to enter /notify some word and have |
| | 179 | // that word notified back to them. This command runs with high priority, |
| | 180 | // and can be used in both group and standard chat messages |
| | 181 | notify_command_id = purple_cmd_register |
| 168 | | PURPLE_CMD_FLAG_CHAT, /* flags saying where |
| 169 | | command can be used */ |
| 170 | | |
| 171 | | NULL, /* We do not need to pass |
| 172 | | plugin ID */ |
| 173 | | |
| 174 | | notify_cb, /* Name of the callback |
| 175 | | function */ |
| 176 | | notify_help, |
| 177 | | |
| 178 | | NULL /* We do not need any special |
| 179 | | user defined data here */ |
| | 186 | PURPLE_CMD_FLAG_CHAT, /* command usage flags */ |
| | 187 | PLUGIN_ID, /* Plugin ID */ |
| | 188 | notify_cb, /* Callback function */ |
| | 189 | notify_help, /* Help message */ |
| | 190 | NULL /* Any special user-defined data */ |
| | 198 | /** |
| | 199 | * Because we added a pointer to this function in the unload section of our |
| | 200 | * PurplePluginInfo, this function is called when the plugin unloads. |
| | 201 | * Here we're using it to show off the capabilities of the |
| | 202 | * command API by unregistering a few commands. We return TRUE to tell libpurple |
| | 203 | * it's safe to continue unloading. |
| | 204 | */ |
| | 205 | static gboolean |
| | 206 | plugin_unload(PurplePlugin *plugin) |
| | 207 | { |
| | 208 | purple_cmd_unregister(log_command_id); |
| | 209 | purple_cmd_unregister(notify_command_id); |
| | 210 | |
| | 211 | /* Just return true to tell libpurple to finish unloading. */ |
| | 212 | return TRUE; |
| | 213 | } |
| | 214 | |
| | 215 | /** |
| | 216 | * Struct used to let Pidgin understand our plugin |
| | 217 | */ |
| 188 | | PURPLE_PLUGIN_MAGIC, /* magic number */ |
| 189 | | PURPLE_MAJOR_VERSION, /* purple major */ |
| 190 | | PURPLE_MINOR_VERSION, /* purple minor */ |
| 191 | | PURPLE_PLUGIN_STANDARD, /* plugin type */ |
| 192 | | NULL, /* UI requirement */ |
| 193 | | 0, /* flags */ |
| 194 | | NULL, /* dependencies */ |
| 195 | | PURPLE_PRIORITY_DEFAULT, /* priority */ |
| 196 | | |
| 197 | | PLUGIN_ID, /* id */ |
| 198 | | "Command API Example", /* name */ |
| 199 | | "1.0", /* version */ |
| 200 | | "Command API Example", /* summary */ |
| 201 | | "Command API Example", /* description */ |
| 202 | | PLUGIN_AUTHOR, /* author */ |
| 203 | | "http://pidgin.im", /* homepage */ |
| 204 | | |
| 205 | | plugin_load, /* load */ |
| 206 | | NULL, /* unload */ |
| 207 | | NULL, /* destroy */ |
| 208 | | |
| 209 | | NULL, /* ui info */ |
| 210 | | NULL, /* extra info */ |
| 211 | | NULL, /* prefs info */ |
| 212 | | NULL, /* actions */ |
| 213 | | NULL, /* reserved */ |
| 214 | | NULL, /* reserved */ |
| 215 | | NULL, /* reserved */ |
| 216 | | NULL /* reserved */ |
| | 219 | PURPLE_PLUGIN_MAGIC, /* magic number */ |
| | 220 | PURPLE_MAJOR_VERSION, /* purple major */ |
| | 221 | PURPLE_MINOR_VERSION, /* purple minor */ |
| | 222 | PURPLE_PLUGIN_STANDARD, /* plugin type */ |
| | 223 | NULL, /* UI requirement */ |
| | 224 | 0, /* flags */ |
| | 225 | NULL, /* dependencies */ |
| | 226 | PURPLE_PRIORITY_DEFAULT, /* priority */ |
| | 227 | |
| | 228 | PLUGIN_ID, /* id */ |
| | 229 | "Command API Example", /* name */ |
| | 230 | "1.0", /* version */ |
| | 231 | "Command API Example", /* summary */ |
| | 232 | "Command API Example", /* description */ |
| | 233 | PLUGIN_AUTHOR, /* author */ |
| | 234 | "http://pidgin.im", /* homepage */ |
| | 235 | |
| | 236 | plugin_load, /* load */ |
| | 237 | plugin_unload, /* unload */ |
| | 238 | NULL, /* destroy */ |
| | 239 | |
| | 240 | NULL, /* ui info */ |
| | 241 | NULL, /* extra info */ |
| | 242 | NULL, /* prefs info */ |
| | 243 | NULL, /* actions */ |
| | 244 | NULL, /* reserved */ |
| | 245 | NULL, /* reserved */ |
| | 246 | NULL, /* reserved */ |
| | 247 | NULL /* reserved */ |
| 232 | | To test (we will assume you are using Pidgin), go to Tools->Plugins and enable the Command API Example plugin. Also, go to Help->Debug Window to show the Debug Window. Open an IM chat session, and type ''/log my log message here''. Your message should show up in the Debug Window. Then type ''/notify Hello!''. You should receive a notification box saying Hello! Also, be sure to try ''/notify Hello World!'' and not that the command fails, because you input multiple arguments (2) when it was only expecting a single value. |
| | 262 | To test (we will assume you are using Pidgin), go to Tools->Plugins and enable the Command API Example plugin. Also, go to Help->Debug Window to show the Debug Window. Open an IM chat session, and type |
| | 263 | {{{ |
| | 264 | /log my log message here |
| | 265 | }}} |
| | 266 | Your message should show up in the Debug Window. Then type |
| | 267 | {{{ |
| | 268 | /notify Hello! |
| | 269 | }}} |
| | 270 | You should receive a notification box saying '''Hello!''' Also, be sure to try |
| | 271 | {{{ |
| | 272 | /notify Hello World! |
| | 273 | }}} |
| | 274 | Note that the command fails, because you input multiple arguments (2) when it was only expecting a single value. It prints ''Syntax Error: You typed the wrong number of arguments to that command.'' |
| | 275 | |
| | 276 | Lastly, if you disable the Command API Example plugin, and then type a command, you will send an IM. Try it! |
| | 277 | {{{ |
| | 278 | /log why is this not working now |
| | 279 | }}} |
| | 280 | |
| | 281 | |
| 235 | | The command API provides a basic command framework for plugins, which can be an extremely valuable resource to plugin authors. The other areas we didn't cover here include much of the true power of the command API, but we will leave those as an area for your exploration at least for now. This document is done, but there are still others in the [wiki:CHowTo C Plugin How-To] for you to explore! |
| 236 | | |
| 237 | | == Updates Needed to this page == |
| 238 | | * Need to clean up the commands (purple_cmd_unregister) at unload. |
| | 284 | The command API provides a basic command framework for plugins, which can be an extremely valuable resource to plugin authors. The other areas we didn't cover here include much of the true power of the command API, but we will leave those as an area for your exploration. This document is done, but there are still others in the [wiki:CHowTo C Plugin How-To] for you to explore! |
