diff options
| author | Gary Kramlich <grim@reaperworld.com> | 2021-11-05 03:23:36 -0500 |
|---|---|---|
| committer | Gary Kramlich <grim@reaperworld.com> | 2021-11-05 03:23:36 -0500 |
| commit | 0ce8b9162c422cd9a0fc3eff11fdfacf915e97f7 (patch) | |
| tree | ad9ebfe517e58e9f144bf7b0469aed6da4fbf9e7 /doc | |
| parent | 64c5f255fec2b2ab65a7de4334c4c0e8f1f132e5 (diff) | |
| download | pidgin-0ce8b9162c422cd9a0fc3eff11fdfacf915e97f7.tar.gz | |
Convert the libpurple docs to gi-docgen
Testing Done:
Built the docs locally and in convey.
Reviewed at https://reviews.imfreedom.org/r/1115/
Diffstat (limited to 'doc')
41 files changed, 3323 insertions, 4727 deletions
diff --git a/doc/reference/libpurple/code_contributions.md b/doc/reference/libpurple/code_contributions.md new file mode 100644 index 0000000000..dc2fc48e3e --- /dev/null +++ b/doc/reference/libpurple/code_contributions.md @@ -0,0 +1,330 @@ +Title: Code Contributions +Slug: code-contributions + +## Code Contributions + +### Introduction + +All of the Pidgin related projects use [Review +Board](https://reviewboard.org/) for handling contributions at +[reviews.imfreedom.org](https://reviews.imfreedom.org). + +### First Time Setup + +There are a few things you'll need to set up to be able to submit a code +review to these projects. This includes installing +[RBTools](https://www.reviewboard.org/downloads/rbtools/) +as well as some additional +[Mercurial](https://www.mercurial-scm.org/) +configuration. + +#### Install RBTools + +The recommended way to install RBTools is via pip and can be done with the +following command. + +```sh +pip3 install -U "RBTools>=1.0.3" +``` +Once RBTools is installed you need to make sure that `rbt` is available on your +`$PATH`. To do this, you may need to add `$HOME/.local/bin` to your `$PATH`. +The exact procedure to do this is dependent on your setup and outside of the +scope of this document. + +#### Mercurial Configuration + +This configuration for Mercurial is to make your life as a contributor easier. +There a few different ways to configure Mercurial, but these instructions will +update your user specific configuration in `$HOME/.hgrc`. + +The first thing we need to do is to install the evolve extension. This +extension makes rewriting history safe and we use it extensively in our +repositories. You can install it with a simple `pip3 install -U hg-evolve`. We +will enable it below with some other bundled extensions, but you can find more +information about it +[here](https://www.mercurial-scm.org/wiki/EvolveExtension). + +When working with Mercurial repositories it is very important to make sure that +your username is set properly as it is added to every commit you make. To set +your username you must add it to the `[ui]` section in your `$HOME/.hgrc` like +the following example. + +```ini +[ui] +username = Full Name <email@example.com> +``` + +Next we need to make sure that the ***evolve*** and ***rebase*** extensions are +loaded. To do so add the lines in the following example. You do not need to put +anything after the `=` as this will tell Mercurial to look for them in the +default places for extensions. + +```ini +[extensions] +evolve = +rebase = +``` + +Next we're going to create a ***revsetalias***. This will be used to make it +easier to look at your history and submit your review request. + +```ini +[revsetalias] +wip = only(.,default) +``` + +This alias will show us just the commits that are on our working branch and not +on the default branch. The default branch is where all accepted code +contributions go. Optionally, you can add the `wip` command alias below which +will show you the revision history of what you are working on. + +```ini +[alias] +wip = log --graph --rev wip +``` + +There are quite a few other useful configuration changes you can make, and a +few examples can be found below. + +```ini +[ui] +# update a large number of settings for a better user experience, highly +# recommended!! +tweakdefaults = true + +[alias] +# make hg log show the graph as well as commit phase +lg = log --graph --template phases +``` + +Below is all of the above configuration settings to make it easier to +copy/paste. + +```ini +[ui] +username = Full Name <email@example.com> +# update a large number of settings for a better user experience, highly +# recommended!! +tweakdefaults = true + +[extensions] +evolve = +rebase = + +[alias] +# make hg log show the graph as well as commit phase +lg = log --graph --template phases + +# show everything between the upstream and your wip +wip = log --graph --rev wip + +[revsetalias] +wip = only(.,default) +``` + +#### Log in to Review Board + +To be able to submit a review request you need to have an account on our +JetBrains Hub instance at [hub.imfreedom.org](https://hub.imfreedom.org). You +can create an account here in a number of ways and even turn on two factor +authentication. But please note that if you turn on two factor authentication +you will need to create an [application +password](https://www.jetbrains.com/help/hub/application-passwords.html) to be +able to login to Review Board. + +Once you have that account you can use it to login our Review Board instance at +[reviews.imfreedom.org](https://reviews.imfreedom.org). Please note, you will +have to login via the web interface before being able to use RBTools. + +Once you have an account and have logged into our Review Board site, you can +begin using RBTools. In your shell, navigate to a Mercurial clone of one of the +Pidgin or purple-related projects, then run the `rbt login` command. You should +only need to do this once, unless you change your password or have run the `rbt +logout` command. + +### Creating a New Review Request + +Before starting a new review request, you should make sure that your +local copy of the repository is up to date. To do so, make sure you are +on the ***default*** branch via +`hg update default`. Once you are on the +***default*** branch, you can update your copy with +`hg pull --update`. Now that you're starting with the most +recent code, you can proceed with your contributions. + +While it's not mandatory, it is highly recommended that you work on your +contributions via a branch. If you don't go this path, you will have +issues after your review request is merged. This branch name can be +whatever you like as it will not end up in the main repositories, and +you can delete it from your local repository after it is merged. See +[cleanup](#cleanup) for more information. + +You can create the branch with the following command: + +```sh +hg branch my-new-branch-name +``` + +Now that you have a branch started, you can go ahead and work like you normally +would, committing your code at logical times, etc. Once you have some work +committed and you are ready to create a new review request, you can type `rbt +post wip` and you should be good to go. This will create a new review request +using all of the committed work in your repository and will output something +like below. + +```sh +Review request #403 posted. + +https://reviews.imfreedom.org/r/403/ +https://reviews.imfreedom.org/r/403/diff/ +``` + +At this point, your review request has been posted, but it is not yet +published. This means no one can review it yet. To do that, you need to go to +the URL that was output from your `rbt post` command and verify that everything +looks correct. If this review request fixes any bugs, please make sure to enter +their numbers in the bugs field on the right. Also, be sure to review the +actual diff yourself to make sure it includes what you intended it to and +nothing extra. + +Once you are happy with the review request, you can hit the publish button +which will make the review request public and alert the reviewers of its +creation. Optionally you can pass `--open` to `rbt post` in the future to +automatically open the draft review in your web browser. + +`rbt post` has a ton of options, so be sure to check them out with `rbt post +--help`. There are even options to automatically fill out the bugs fixed fields +among other things. + +### Updating an Existing Review Request + +Typically with a code review, you're going to need to make some updates. +However there's also a good chance that your original branching point has +changed as other contributions are accepted. To deal with this you'll need to +rebase your branch on top of the new changes. + +Rebasing, as the name suggests is the act of replaying your previous +commits on top of a new base revision. Mercurial makes this pretty easy. +First, make sure you are on your branch with +`hg up my-branch-name`. Now you can preview the rebase with +`hg rebase -d default --keepbranches --dry-run`. We prefer +doing a dry-run just to make sure there aren't any major surprises. You +may run into some conflicts, but those will have to be fixed regardless. + +If everything looks good, you can run the actual rebase with `hg rebase -d +default --keepbranches`. Again if you run into any conflicts, you will have to +resolve them and they will cause the dry-run to fail. Once you have fixed the +merge conflicts, you'll then need to mark the files as resolved with `hg +resolve --mark filename`. When you have resolved all of the conflicted files +you can continue the rebase with `hg rebase --continue`. You may run into +multiple conflicts, so just repeat until you're done. + +After rebasing you can start addressing the comments in your review and commit +them. Once they are committed, you can update your existing review request +with `rbt post --update`. If for some reason `rbt` can not figure out the +proper review request to update, you can pass the number in via `rbt post +--review-request-id #`. Note that when using `--review-request-id` you no +longer need to specify `--update`. + +Just like an initial `rbt post`, the updated version will be in a draft state +until you publish it. So again, you'll need to visit the URL that was output, +verify everything, and click the publish button. + +### Landing a Review Request + +This will typically only be done by the Pidgin developers with push access. If +you want to test a patch from a review request, please see the [patch](#path) +section below. + +It is ***HIGHLY*** recommended that you use a separate clone of the repository +in question when you want to land review requests. This makes it much easier +to avoid accidentally pushing development work to the canonical repository +which makes everyone's life easier. Also, the mainline repositories now auto +publish, so if you do not selectively push commits, all of your draft commits +will be published. You can name this additional clone whatever you like, but +using something like `pidgin-clean` is a fairly common practice. This makes it +easy for you to know that this clone is only meant for landing review requests, +and other admistrative work like updating the ChangeLog and COPYRIGHT files. + +When you are ready to land a review request you need to make sure you are on +the proper branch. In most cases this will be the branch named ***default*** +and can be verified by running the command `hg branch`. Next you need to make +sure that your local copy is up to date. You can do this by running `hg pull +--update`. + +Please note, if you run `hg pull` and then immediately run `hg pull --update` +you will ***not*** update to the most recent commit as this new invocation of +`hg pull` has not actually pulled in any new commits. To properly update, +you'll need to run `hg update` instead. + +Once your local copy is up to date you can land the review request with `rbt +land --no-push --review-request-id #` where `#` is the number of the review +request you are landing. The `--no-push` argument is to disable pushing this +commit immediately. Most of our configuration already enables this flag for +you, but if you're in doubt, please use the `--no-push` argument. + +Once the review request has been landed, make sure to verify that the revision +history looks correct, run a test build as well as the unit tests, and if +everything looks good, you can continue with the housekeeping before we finally +push the new commits. + +The housekeeping we need to do entails a few things. If this is a big new +feature or bug fix, we should be documenting this in the ChangeLog file for the +repository. Please follow the existing convention of mentioning the contributor +as well as the issues addressed and the review request number. Likewise, if +this is someone's first contribution you will need to add them to the COPYRIGHT +file in the repository as well. If you had to update either of these files, +review your changes and commit them directly. + +Now that any updates to ChangeLog and COPYRIGHT are completed, we can actually +start pushing the changes back to the canonical repository. Currently not all +of the canonical repositories are publishing repositories so we'll need to +manually mark the commits as public. This is easily accomplished with `hg phase +--public`. ***Note***, if you are not using a separate clone of the canonical +repository you will need to specify a revision to avoid publishing every commit +in your repository. If you run into issues or have more questions about phases +see the [official documentation](https://www.mercurial-scm.org/wiki/Phases). + +Now that the changes have been made public, we can finally push to the +canonical repository with `hg push`. Once that is done, you'll also need to go +and mark the review request as ***Submitted*** in the Review Board web +interface. + +### Testing Patches Locally + +If you want to test a patch locally for any reason, you first need to make sure +that you are on the target branch for the review request which is listed on the +review request page. In most cases this will be the ***default*** branch. +Regardless you'll need to run `hg up branch-name` before applying the patch. + +Now that you are on the correct branch, you can apply the patch with +`rbt patch #` where `#` is the id of the review request you want to test. This +will apply the patch from the review request to your working copy without +committing it. + +Once you're done with your testing you can remove the changes with `hg revert +--no-backup --all`. This will return your repository to exactly what it was +before the patch was applied. The `--no-backup` argument says to not save the +changes that you are reverting and the `--all` argument tells Mercurial to +revert all files. + +### Cleaning up a Landed of Discarded Review Request + +Whether or not your pull request has been accepted, you probably want to clean +it up from your local repository. To do so, you need to update to a branch +other than the branch you built it on. In the following example, we're going to +remove the branch named ***my-new-branch-name*** that we used to create a +review request. + +```sh +hg up default +hg prune -r 'branch(my-new-branch-name)' +``` + +Now, all commits that were on the ***my-new-branch-name*** branch will have +their contents removed but internally Mercurial keeps track that these revisions +have been deleted. + +You can repeat this for any other branches you need to clean up, and you're +done! + diff --git a/doc/reference/libpurple/code_contributions.xml b/doc/reference/libpurple/code_contributions.xml deleted file mode 100644 index 88780734c6..0000000000 --- a/doc/reference/libpurple/code_contributions.xml +++ /dev/null @@ -1,460 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-code-contributions"> - <title>Code Contributions</title> - - <sect2 id="introduction"> - <title>Introduction</title> - <para> - All of the Pidgin related projects use - <ulink url="https://reviewboard.org">Review Board</ulink> for handling - contributions at - <ulink url="https://reviews.imfreedom.org">reviews.imfreedom.org</ulink>. - </para> - </sect2> - - <sect2 id="first-time-setup"> - <title>First Time Setup</title> - <para> - There are a few things you'll need to set up to be able to submit a code - review to these projects. This includes installing - <ulink url="https://www.reviewboard.org/downloads/rbtools/">RBTools</ulink> - as well as some additional - <ulink url="https://www.mercurial-scm.org/">Mercurial</ulink> - configuration. - </para> - - <sect3 id="install-rbtools"> - <title>Install RBTools</title> - - <para> - The recommended way to install RBTools is via pip and can be done with - the following command. - </para> - - <programlisting> -pip3 install -U "RBTools>=1.0.3" -</programlisting> - - <para> - Once RBTools is installed you need to make sure that <code>rbt</code> - is available on your <code>$PATH</code>. To do this, you may need to - add <code>$HOME/.local/bin</code> to your <code>$PATH</code>. The exact - procedure to do this is dependent on your setup and outside of the - scope of this document. - </para> - </sect3> - - <sect3 id="configure-mercurial"> - <title>Mercurial Configuration</title> - - <para> - This configuration for Mercurial is to make your life as a contributor - easier. There a few different ways to configure Mercurial, but these - instructions will update your user specific configuration in - <code>$HOME/.hgrc</code>. - </para> - - <para> - The first thing we need to do is to install the evolve extension. This - extension makes rewriting history safe and we use it extensively in our - repositories. You can install it with a simple <code>pip3 install -U - hg-evolve</code>. We will enable it below with some other bundled - extensions, but you can find more information about it - <ulink url="https://www.mercurial-scm.org/wiki/EvolveExtension">here</ulink>. - </para> - - <para> - When working with Mercurial repositories it is very important to make - sure that your username is set properly as it is added to every commit - you make. To set your username you must add it to the <code>[ui]</code> - section in your <code>$HOME/.hgrc</code> like the following example. - </para> - - <programlisting> -[ui] -username = Full Name <email@example.com> -</programlisting> - - <para> - Next we need to make sure that the <emphasis>evolve</emphasis> - and <emphasis>rebase</emphasis> extensions are loaded. To do so add the - lines in the following example. You do not need to put anything after - the <code>=</code> as this will tell Mercurial to look for them in the - default places for extensions. - </para> - - <programlisting> -[extensions] -evolve = -rebase = -</programlisting> - - <para> - Next we're going to create a <emphasis>revsetalias</emphasis>. This will - be used to make it easier to look at your history and submit your review - request. - </para> - - <programlisting> -[revsetalias] -wip = only(.,default) -</programlisting> - - <para> - This alias will show us just the commits that are on our working branch - and not on the default branch. The default branch is where all - accepted code contributions go. Optionally, you can add the - <code>wip</code> command alias below which will show you the revision - history of what you are working on. - </para> - - <programlisting> -[alias] -wip = log --graph --rev wip -</programlisting> - - <para> - There are quite a few other useful configuration changes you can make, - and a few examples can be found below. - </para> - - <programlisting> -[ui] -# update a large number of settings for a better user experience, highly -# recommended!! -tweakdefaults = true - -[alias] -# make hg log show the graph as well as commit phase -lg = log --graph --template phases -</programlisting> - - <para> - Below is all of the above configuration settings to make it easier to - copy/paste. - </para> - - <programlisting> -[ui] -username = Full Name <email@example.com> -# update a large number of settings for a better user experience, highly -# recommended!! -tweakdefaults = true - -[extensions] -evolve = -rebase = - -[alias] -# make hg log show the graph as well as commit phase -lg = log --graph --template phases - -# show everything between the upstream and your wip -wip = log --graph --rev wip - -[revsetalias] -wip = only(.,default) -</programlisting> - </sect3> - - <sect3 id="login"> - <title>Log in to Review Board</title> - - <para> - To be able to submit a review request you need to have an account on - our JetBrains Hub instance at - <ulink url="https://hub.imfreedom.org">hub.imfreedom.org</ulink>. You - can create an account here in a number of ways and even turn on two - factor authentication. But please note that if you turn on two factor - authentication you will need to create an - <ulink url="https://www.jetbrains.com/help/hub/application-passwords.html">application password</ulink> - to be able to login to Review Board. - </para> - - <para> - Once you have that account you can use it to login our Review Board - instance at - <ulink url="https://reviews.imfreedom.org">reviews.imfreedom.org</ulink>. - Please note, you will have to login via the web interface before being - able to use RBTools. - </para> - - <para> - Once you have an account and have logged into our Review Board site, you - can begin using RBTools. In your shell, navigate to a Mercurial clone of - one of the Pidgin or purple-related projects, then run the - <code>rbt login</code> command. You should only need to do this once, - unless you change your password or have run the <code>rbt logout</code> - command. - </para> - </sect3> - </sect2> - - <sect2 id="create"> - <title>Creating a New Review Request</title> - - <para> - Before starting a new review request, you should make sure that your - local copy of the repository is up to date. To do so, make sure you are - on the <emphasis>default</emphasis> branch via - <code>hg update default</code>. Once you are on the - <emphasis>default</emphasis> branch, you can update your copy with - <code>hg pull --update</code>. Now that you're starting with the most - recent code, you can proceed with your contributions. - </para> - - <para> - While it's not mandatory, it is highly recommended that you work on your - contributions via a branch. If you don't go this path, you will have - issues after your review request is merged. This branch name can be - whatever you like as it will not end up in the main repositories, and - you can delete it from your local repository after it is merged. See - <link linkend="cleanup">cleanup</link> for more information. - </para> - - <para> - You can create the branch with the following command: - </para> - - <programlisting> -hg branch my-new-branch-name -</programlisting> - - <para> - Now that you have a branch started, you can go ahead and work like you - normally would, committing your code at logical times, etc. Once you - have some work committed and you are ready to create a new review - request, you can type <code>rbt post wip</code> and you should be good to - go. This will create a new review request using all of the committed work - in your repository and will output something like below. - </para> - - <programlisting language="screen"> -Review request #403 posted. - -https://reviews.imfreedom.org/r/403/ -https://reviews.imfreedom.org/r/403/diff/ -</programlisting> - - <para> - At this point, your review request has been posted, but it is not yet - published. This means no one can review it yet. To do that, you need to - go to the URL that was output from your <code>rbt post</code> command - and verify that everything looks correct. If this review request fixes - any bugs, please make sure to enter their numbers in the bugs field on - the right. Also, be sure to review the actual diff yourself to make sure - it includes what you intended it to and nothing extra. - </para> - - <para> - Once you are happy with the review request, you can hit the publish - button which will make the review request public and alert the reviewers - of its creation. Optionally you can pass <code>--open</code> to - <code>rbt post</code> in the future to automatically open the draft - review in your web browser. - </para> - - <para> - <code>rbt post</code> has a ton of options, so be sure to check them out - with <code>rbt post --help</code>. There are even options to - automatically fill out the bugs fixed fields among other things. - </para> - </sect2> - - <sect2 id="update"> - <title>Updating an Existing Review Request</title> - - <para> - Typically with a code review, you're going to need to make some updates. - However there's also a good chance that your original branching point - has changed as other contributions are accepted. To deal with this you'll - need to rebase your branch on top of the new changes. - </para> - - <para> - Rebasing, as the name suggests is the act of replaying your previous - commits on top of a new base revision. Mercurial makes this pretty easy. - First, make sure you are on your branch with - <code>hg up my-branch-name</code>. Now you can preview the rebase with - <code>hg rebase -d default --keepbranches --dry-run</code>. We prefer - doing a dry-run just to make sure there aren't any major surprises. You - may run into some conflicts, but those will have to be fixed regardless. - </para> - - <para> - If everything looks good, you can run the actual rebase with - <code>hg rebase -d default --keepbranches</code>. Again if you run into - any conflicts, you will have to resolve them and they will cause the - dry-run to fail. Once you have fixed the merge conflicts, you'll then - need to mark the files as resolved with - <code>hg resolve --mark filename</code>. When you have resolved all of - the conflicted files you can continue the rebase with - <code>hg rebase --continue</code>. You may run into multiple conflicts, - so just repeat until you're done. - </para> - - <para> - After rebasing you can start addressing the comments in your review and - commit them. Once they are committed, you can update your existing - review request with <code>rbt post --update</code>. If for some reason - <code>rbt</code> can not figure out the proper review request to - update, you can pass the number in via - <code>rbt post --review-request-id #</code>. Note that when using - <code>--review-request-id</code> you no longer need to specify - <code>--update</code>. - </para> - - <para> - Just like an initial <code>rbt post</code>, the updated version will be - in a draft state until you publish it. So again, you'll need to visit the - URL that was output, verify everything, and click the publish button. - </para> - </sect2> - - <sect2 id="land"> - <title>Landing a Review Request</title> - - <para> - This will typically only be done by the Pidgin developers with push - access. If you want to test a patch from a review request, please see the - <link linkend="patch">patch</link> section below. - </para> - - <para> - It is <emphasis>HIGHLY</emphasis> recommended that you use a separate - clone of the repository in question when you want to land review requests. - This makes it much easier to avoid accidentally pushing development work - to the canonical repository which makes everyone's life easier. Also, the - mainline repositories now auto publish, so if you do not selectively push - commits, all of your draft commits will be published. You can name this - additional clone whatever you like, but using something like - <code>pidgin-clean</code> is a fairly common practice. This makes it easy - for you to know that this clone is only meant for landing review requests, - and other admistrative work like updating the ChangeLog and COPYRIGHT - files. - </para> - - <para> - When you are ready to land a review request you need to make sure you are - on the proper branch. In most cases this will be the branch named - <emphasis>default</emphasis> and can be verified by running the command - <code>hg branch</code>. Next you need to make sure that your local copy - is up to date. You can do this by running <code>hg pull --update</code>. - </para> - - <para> - Please note, if you run <code>hg pull</code> and then immediately run - <code>hg pull --update</code> you will <emphasis>not</emphasis> update to - the most recent commit as this new invocation of <code>hg pull</code> has - not actually pulled in any new commits. To properly update, you'll need - to run <code>hg update</code> instead. - </para> - - <para> - Once your local copy is up to date you can land the review request with - <code>rbt land --no-push --review-request-id #</code> where <code>#</code> - is the number of the review request you are landing. The - <code>--no-push</code> argument is to disable pushing this commit - immediately. Most of our configuration already enables this flag for you, - but if you're in doubt, please use the <code>--no-push</code> argument. - </para> - - <para> - Once the review request has been landed, make sure to verify that the - revision history looks correct, run a test build as well as the unit - tests, and if everything looks good, you can continue with the - housekeeping before we finally push the new commits. - </para> - - <para> - The housekeeping we need to do entails a few things. If this is a big new - feature or bug fix, we should be documenting this in the ChangeLog file - for the repository. Please follow the existing convention of mentioning - the contributor as well as the issues addressed and the review request - number. Likewise, if this is someone's first contribution you will need - to add them to the COPYRIGHT file in the repository as well. If you had - to update either of these files, review your changes and commit them - directly. - </para> - - <para> - Now that any updates to ChangeLog and COPYRIGHT are completed, we can - actually start pushing the changes back to the canonical repository. - Currently not all of the canonical repositories are publishing - repositories so we'll need to manually mark the commits as public. This - is easily accomplished with <code>hg phase --public</code>. - <emphasis>Note</emphasis>, if you are not using a separate clone of the - canonical repository you will need to specify a revision to avoid - publishing every commit in your repository. If you run into issues or - have more questions about phases see the - <ulink url="https://www.mercurial-scm.org/wiki/Phases">official documentation</ulink>. - </para> - - <para> - Now that the changes have been made public, we can finally push to the - canonical repository with <code>hg push</code>. Once that is done, you'll - also need to go and mark the review request as - <emphasis>Submitted</emphasis> in the Review Board web interface. - </para> - </sect2> - - <sect2 id="patch"> - <title>Testing Patches Locally</title> - - <para> - If you want to test a patch locally for any reason, you first need to - make sure that you are on the target branch for the review request which - is listed on the review request page. In most cases this will be the - <emphasis>default</emphasis> branch. Regardless you'll need to run - <code>hg up branch-name</code> before applying the patch. - </para> - - <para> - Now that you are on the correct branch, you can apply the patch with - <code>rbt patch #</code> where <code>#</code> is the id of the review - request you want to test. This will apply the patch from the review - request to your working copy without committing it. - </para> - - <para> - Once you're done with your testing you can remove the changes with - <code>hg revert --no-backup --all</code>. This will return your - repository to exactly what it was before the patch was applied. The - <code>--no-backup</code> argument says to not save the changes that you - are reverting and the <code>--all</code> argument tells Mercurial to - revert all files. - </para> - </sect2> - - <sect2 id="cleanup"> - <title>Cleaning up a Landed or Discarded Review Request</title> - - <para> - Whether or not your pull request has been accepted, you probably want to - clean it up from your local repository. To do so, you need to update to - a branch other than the branch you built it on. In the following example, - we're going to remove the branch named - <emphasis>my-new-branch-name</emphasis> that we used to create a review - request. - </para> - - <programlisting> -hg up default -hg prune -r 'branch(my-new-branch-name)' -</programlisting> - - <para> - Now, all commits that were on the <emphasis>my-new-branch-name</emphasis> - branch will have their contents removed but interally Mercurial keeps - track that these revisions have been deleted. - </para> - - <para> - You can repeat this for any other branches you need to clean up, and - you're done! - </para> - </sect2> -</chapter> diff --git a/doc/reference/libpurple/libpurple-docs.xml b/doc/reference/libpurple/libpurple-docs.xml deleted file mode 100644 index 189cd6a10b..0000000000 --- a/doc/reference/libpurple/libpurple-docs.xml +++ /dev/null @@ -1,218 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ - -<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> -<!ENTITY version SYSTEM "version.xml"> -]> -<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> - <bookinfo> - <title>Purple Reference Manual</title> - <abstract> - <title>Libpurple &version;</title> - <para> - libpurple is intended to be the core of an IM program. Pidgin is a GTK+ - frontend to libpurple, and Finch is an ncurses frontend built using - libgnt (GLib Ncurses Toolkit). - </para> - </abstract> - </bookinfo> - - <part id="development"> - <title>Development</title> - - <xi:include href="mercurial.xml" /> - <xi:include href="code_contributions.xml" /> - </part> - - <part id="tutorial"> - <title>Tutorials</title> - - <xi:include href="tut_c_plugins.xml" /> - <xi:include href="tut_signals.xml" /> - </part> - - <part id="API"> - <title>API Reference</title> - - <xi:include href="xml/account.xml" /> - <xi:include href="xml/accounts.xml" /> - <xi:include href="xml/action.xml" /> - <xi:include href="xml/blistnode.xml" /> - <xi:include href="xml/buddy.xml" /> - <xi:include href="xml/buddylist.xml" /> - <xi:include href="xml/buddyicon.xml" /> - <xi:include href="xml/chat.xml" /> - <xi:include href="xml/circularbuffer.xml" /> - <xi:include href="xml/contact.xml" /> - <xi:include href="xml/connection.xml" /> - <xi:include href="xml/conversations.xml" /> - <xi:include href="xml/countingnode.xml" /> - <xi:include href="xml/debug.xml" /> - <xi:include href="xml/eventloop.xml" /> - <xi:include href="xml/group.xml" /> - <xi:include href="xml/xfer.xml" /> - <xi:include href="xml/idle.xml" /> - <xi:include href="xml/memorypool.xml" /> - <xi:include href="xml/nat-pmp.xml" /> - <xi:include href="xml/network.xml" /> - <xi:include href="xml/notify.xml" /> - <xi:include href="xml/plugins.xml" /> - <xi:include href="xml/prefs.xml" /> - <xi:include href="xml/pluginpref.xml" /> - <xi:include href="xml/proxy.xml" /> - <xi:include href="xml/purple-gio.xml" /> - <xi:include href="xml/purpleaccountoption.xml" /> - <xi:include href="xml/purpleaccountpresence.xml" /> - <xi:include href="xml/purpleaccountusersplit.xml" /> - <xi:include href="xml/purpleattentiontype.xml" /> - <xi:include href="xml/purplebuddypresence.xml" /> - <xi:include href="xml/purplechatconversation.xml" /> - <xi:include href="xml/purplechatuser.xml" /> - <xi:include href="xml/purpleconversation.xml" /> - <xi:include href="xml/purpleconversationmanager.xml" /> - <xi:include href="xml/purpleconversationuiops.xml" /> - <xi:include href="xml/purpledebugui.xml" /> - <xi:include href="xml/purplehistoryadapter.xml" /> - <xi:include href="xml/purplehistorymanager.xml" /> - <xi:include href="xml/purpleimconversation.xml" /> - <xi:include href="xml/purplekeyvaluepair.xml" /> - <xi:include href="xml/purplemarkup.xml" /> - <xi:include href="xml/purpleoptions.xml" /> - <xi:include href="xml/purpleplugininfo.xml" /> - <xi:include href="xml/purplepresence.xml" /> - <xi:include href="xml/purplewhiteboard.xml" /> - <xi:include href="xml/purplewhiteboardmanager.xml" /> - <xi:include href="xml/purplewhiteboardops.xml" /> - <xi:include href="xml/purplewhiteboarduiops.xml" /> - <xi:include href="xml/purpleuiinfo.xml" /> - <xi:include href="xml/queuedoutputstream.xml" /> - <xi:include href="xml/signals.xml" /> - <xi:include href="xml/request.xml" /> - <xi:include href="xml/request-datasheet.xml" /> - <xi:include href="xml/roomlist.xml" /> - <xi:include href="xml/savedstatuses.xml" /> - <xi:include href="xml/server.xml" /> - <xi:include href="xml/core.xml" /> - <xi:include href="xml/status.xml" /> - <xi:include href="xml/stun.xml" /> - <xi:include href="xml/theme.xml" /> - <xi:include href="xml/theme-loader.xml" /> - <xi:include href="xml/theme-manager.xml" /> - <xi:include href="xml/trie.xml" /> - <xi:include href="xml/upnp.xml" /> - <xi:include href="xml/xmlnode.xml" /> - <xi:include href="xml/version.xml" /> - <xi:include href="xml/util.xml" /> - </part> - - <part id="Credentials"> - <title>Credentials</title> - - <xi:include href="xml/purplecredentialmanager.xml" /> - <xi:include href="xml/purplecredentialprovider.xml" /> - <xi:include href="xml/purplenoopcredentialprovider.xml" /> - </part> - - <part id="Protocols"> - <title>Protocols</title> - - <xi:include href="xml/protocols.xml" /> - <xi:include href="xml/purpleprotocol.xml" /> - <xi:include href="xml/purpleprotocolattention.xml" /> - <xi:include href="xml/purpleprotocolchat.xml" /> - <xi:include href="xml/purpleprotocolclient.xml" /> - <xi:include href="xml/purpleprotocolfactory.xml" /> - <xi:include href="xml/purpleprotocolim.xml" /> - <xi:include href="xml/purpleprotocolmanager.xml" /> - <xi:include href="xml/purpleprotocolmedia.xml" /> - <xi:include href="xml/purpleprotocolprivacy.xml" /> - <xi:include href="xml/purpleprotocolroomlist.xml" /> - <xi:include href="xml/purpleprotocolserver.xml" /> - </part> - - <part id="Submodules"> - <title>Submodules</title> - <chapter id="messages"> - <title>Messaging</title> - - <xi:include href="xml/purplemessage.xml" /> - <xi:include href="xml/purpleattachment.xml" /> - <xi:include href="xml/cmds.xml" /> - </chapter> - - <chapter id="image"> - <title>Graphics</title> - - <xi:include href="xml/image.xml" /> - <xi:include href="xml/image-store.xml" /> - </chapter> - - <chapter id="media"> - <title>Media APIs</title> - - <xi:include href="xml/media.xml" /> - <xi:include href="xml/media-gst.xml" /> - <xi:include href="xml/mediamanager.xml" /> - <xi:include href="xml/candidate.xml" /> - <xi:include href="xml/codec.xml" /> - <xi:include href="xml/backend-iface.xml" /> - <xi:include href="xml/enum-types.xml" /> - </chapter> - </part> - - <part id="signals"> - <title>Purple-signals Reference</title> - - <xi:include href="signals_account.xml" /> - <xi:include href="signals_blist.xml" /> - <xi:include href="signals_certificate.xml" /> - <xi:include href="signals_cmd.xml" /> - <xi:include href="signals_connection.xml" /> - <xi:include href="signals_conversation.xml" /> - <xi:include href="signals_core.xml" /> - <xi:include href="signals_xfer.xml" /> - <xi:include href="signals_log.xml" /> - <xi:include href="signals_notify.xml" /> - <xi:include href="signals_plugin.xml" /> - <xi:include href="signals_savedstatus.xml" /> - <xi:include href="signals_jabber.xml" /> - </part> - - <xi:include href="plugin_ids.xml" /> - <xi:include href="plugin_i18n.xml" /> - <xi:include href="ui_ops.xml" /> - - <part> - <title>Appendices</title> - - <index id="api-index-full"> - <title>API Index</title> - <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-deprecated"> - <title>Index of deprecated symbols</title> - <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include> - </index> - - <index id="api-3.0.0"> - <title>Index of new symbols in 3.0.0</title> - <xi:include href="xml/api-index-3.0.0.xml"><xi:fallback /></xi:include> - </index> - <index id="api-2.14.0"> - <title>Index of new symbols in 2.14.0</title> - <xi:include href="xml/api-index-2.14.0.xml"><xi:fallback /></xi:include> - </index> - <index id="api-2.13.0"> - <title>Index of new symbols in 2.13.0</title> - <xi:include href="xml/api-index-2.13.0.xml"><xi:fallback /></xi:include> - </index> - <index id="api-2.11.0"> - <title>Index of new symbols in 2.11.0</title> - <xi:include href="xml/api-index-2.11.0.xml"><xi:fallback /></xi:include> - </index> - - <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> - </part> -</book> diff --git a/doc/reference/libpurple/libpurple.toml.in b/doc/reference/libpurple/libpurple.toml.in new file mode 100644 index 0000000000..0272c2279a --- /dev/null +++ b/doc/reference/libpurple/libpurple.toml.in @@ -0,0 +1,58 @@ +[library] +version = "@PURPLE_VERSION@" +browse_url = "https://keep.imfreedom.org/pidgin/pidgin/" +repository_url = "https://keep.imfreedom.org/pidgin/pidgin/" +website_url = "https://keep.imfreedom.org/pidgin/pidgin/" +authors = "Pidgin Developers" +logo_url = "" +license = "GPL-2.0-or-later" +description = "Purple Universal Chat Library" +dependencies = [ "GLib-2.0", "GObject-2.0", "GPlugin-1.0" ] +devhelp = true +search_index = true + + [dependencies."GLib-2.0"] + name = "GLib" + description = "General-purpose, portable utility library." + docs_url = "https://docs.gtk.org/glib/" + + [dependencies."GObject-2.0"] + name = "GObject" + description = "The base type system library" + docs_url = "https://docs.gtk.org/gobject/" + + [dependencies."GPlugin-1.0"] + name = "GPlugin" + description = "GPlugin Plugin Library" + docs_urls = "https://docs.imfreedom.org/gplugin/" + +[theme] +name = "basic" +show_index_summary = true +show_class_hierarchy = true + +[source-location] +base_url = "https://keep.imfreedom.org/pidgin/pidgin/file/default/" + +[extra] +# The same order will be used when generating the index +content_files = [ + "code_contributions.md", + "mercurial.md", + "plugin_i18n.md", + "plugin_ids.md", + "signals_account.md", + "signals_blist.md", + "signals_cmd.md", + "signals_connection.md", + "signals_conversation.md", + "signals_core.md", + "signals_jabber.md", + "signals_notify.md", + "signals_savedstatus.md", + "signals_xfer.md", + "tut_c_plugins.md", +] +content_images = [ +] +urlmap_file = "urlmap.js" diff --git a/doc/reference/libpurple/mercurial.md b/doc/reference/libpurple/mercurial.md new file mode 100644 index 0000000000..70a5835b3e --- /dev/null +++ b/doc/reference/libpurple/mercurial.md @@ -0,0 +1,85 @@ +Title: Using Pidgin Mercurial +Slug: using-pidgin-mercurial + +## Using Pidgin Mercurial + +### Introduction + +These instructions will help you clone a copy of any of the Pidgin +related [Mercurial](https://mercurial-scm.org) +repositories and keep them up to date. + +These instructions are just for cloning/updating the Pidgin repositories. +If you're looking for documentation on contributing code, please see the +[Code Contributions](code_contributions.html) +page after you have successfully cloned the repository from this page. + +### Cloning + +In Distributed Version Control, ***cloning*** is the act +of acquiring a source repository. All of the Pidgin repositories are +hosted in Mercurial at +[keep.imfreedom.org](https://keep.imfreedom.org/). To +clone them you will be using the command +`hg clone <URL>`. The specific URL can be looked up in +the table below depending what you are trying to clone. + +> If you are trying to build Pidgin 3, you can just clone that repository and +> the build system will automatically clone the other repositories for you. + +#### Repositories + +[https://keep.imfreedom.org/gplugin/gplugin/](https://keep.imfreedom.org/gplugin/gplugin/) +: The plugin library used in Pidgin 3. + +[https://keep.imfreedom.org/libgnt/libgnt/](https://keep.imfreedom.org/libgnt/libgnt/) +: The toolkit library used in Finch. + +[https://keep.imfreedom.org/pidgin/pidgin/](https://keep.imfreedom.org/pidgin/pidgin/) +: The main Pidgin repository that contains LibPurple, Pidgin, and Finch. + +[https://keep.imfreedom.org/talkatu/talkatu/](https://keep.imfreedom.org/talkatu/talkatu/) +: The conversation widgets used in Pidgin 3. + +You can see an example clone of Talkatu below but all of the repositories will +output a similar result. + +```sh +$ hg clone https://keep.imfreedom.org/talkatu/talkatu +destination directory: talkatu +requesting all changes +adding changesets +adding manifests +adding file changes +added 348 changesets with 1074 changes to 268 files +new changesets 0feed1461a4a:f0fda4aace2d +updating to branch default +109 files updated, 0 files merged, 0 files removed, 0 files unresolved +``` + +### Keeping Your Clone Up To Date + +If you are just tracking Pidgin development and are not contributing, chances +are you are still on the ***default*** branch. But let's make sure, and run +`hg update default`. This will change to the ***default*** branch if you're +not currently on it or do nothing. + +Now that you are on the ***default*** branch, you can +simply run `hg pull --update` to pull in all new changes and +update your local copy. Please note, if you accidentally run +`hg pull`, that is without the update, a subsequent +`hg pull --update` will not update to the latest revisions as +this invocation of `hg pull` did not find any new revisions. To +properly update in this scenario, you'll need to run +`hg update`. + +Below is an example of updating Talkatu when it's already up to date. + +```sh +$ hg pull --update +pulling from https://keep.imfreedom.org/talkatu/talkatu +searching for changes +no changes found +``` + +At this point you can review the code, build it, patch it, etc. diff --git a/doc/reference/libpurple/mercurial.xml b/doc/reference/libpurple/mercurial.xml deleted file mode 100644 index ae8a733456..0000000000 --- a/doc/reference/libpurple/mercurial.xml +++ /dev/null @@ -1,144 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-using-mercurial"> - <title>Using Pidgin Mercurial</title> - - <sect2 id="introduction"> - <title>Introduction</title> - - <para> - These instructions will help you clone a copy of any of the Pidgin - related <ulink url="https://mercurial-scm.org">Mercurial</ulink> - repositories and keep them up to date. - </para> - - <note> - These instructions are just for cloning/updating the Pidgin repositories. - If you're looking for documentation on contributing code, please see the - <link linkend="chapter-code-contributions">Code Contributions</link> - page after you have successfully cloned the repository from this page. - </note> - </sect2> - - <sect2 id="cloning"> - <title>Cloning</title> - - <para> - In Distributed Version Control, <emphasis>cloning</emphasis> is the act - of acquiring a source repository. All of the Pidgin repositories are - hosted in Mercurial at - <ulink url="https://keep.imfreedom.org/">keep.imfreedom.org</ulink>. To - clone them you will be using the command - <code>hg clone <URL></code>. The specific URL can be looked up in - the table below depending what you are trying to clone. - </para> - - <note> - If you are trying build Pidgin 3, you can just clone that repository and - the build system will automatically clone the other repositories for you. - </note> - - <table label="Repository URLs"> - <tgroup cols="3"> - <thead> - <row> - <entry>Name</entry> - <entry>URL</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>GPlugin</entry> - <entry> - <ulink url="https://keep.imfreedom.org/gplugin/gplugin"></ulink> - </entry> - <entry>The plugin library used in Pidgin 3.</entry> - </row> - <row> - <entry>LibGNT</entry> - <entry> - <ulink url="https://keep.imfreedom.org/libgnt/libgnt"></ulink> - </entry> - <entry>The toolkit library used in Finch.</entry> - </row> - <row> - <entry>Pidgin</entry> - <entry> - <ulink url="https://keep.imfreedom.org/pidgin/pidgin"></ulink> - </entry> - <entry> - The main pidgin repository that contains LibPurple, Pidgin, and - Finch. - </entry> - </row> - <row> - <entry>Talkatu</entry> - <entry> - <ulink url="https://keep.imfreedom.org/talkatu/talkatu"></ulink> - </entry> - <entry>The conversation widgets used in Pidgin 3.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - You can see an example clone of Talkatu below but all of the repositories - will output a similar result. - </para> - - <programlisting language="screen"> -$ hg clone https://keep.imfreedom.org/talkatu/talkatu -destination directory: talkatu -requesting all changes -adding changesets -adding manifests -adding file changes -added 348 changesets with 1074 changes to 268 files -new changesets 0feed1461a4a:f0fda4aace2d -updating to branch default -109 files updated, 0 files merged, 0 files removed, 0 files unresolved -</programlisting> - </sect2> - - <sect2 id="updating"> - <title>Keeping Your Clone Up to Date</title> - - <para> - If you are just tracking Pidgin development and are not contributing, - chances are you are still on the <emphasis>default</emphasis> branch. But - let's make sure, and run <code>hg update default</code>. This will change - to the <emphasis>default</emphasis> branch if you're not currently on it - or do nothing. - </para> - - <para> - Now that you are on the <emphasis>default</emphasis> branch, you can - simply run <code>hg pull --update</code> to pull in all new changes and - update your local copy. Please note, if you accidentally run - <code>hg pull</code>, that is without the update, a subsequent - <code>hg pull --update</code> will not update to the latest revisions as - this invocation of <code>hg pull</code> did not find any new revisions. To - properly update in this scenario, you'll need to run - <code>hg update</code>. - </para> - - <para> - Below is an example of updating Talkatu when it's already up to date. - </para> - - <programlisting> -$ hg pull --update -pulling from https://keep.imfreedom.org/talkatu/talkatu -searching for changes -no changes found -</programlisting> - - <para> - At this point you can review the code, build it, patch it, etc. - </para> - </sect2> -</chapter> diff --git a/doc/reference/libpurple/meson.build b/doc/reference/libpurple/meson.build index ab77378186..0e4e909f29 100644 --- a/doc/reference/libpurple/meson.build +++ b/doc/reference/libpurple/meson.build @@ -1,71 +1,49 @@ -DOC_MODULE = 'libpurple' - -# Header files or dirs to ignore when scanning. Use base file/dir names -ignore_hfiles = [ - 'example', - 'plugins', - 'protocols', - 'tests', - 'tests.h', - 'win32', - 'backend-fs2.h', - 'glibcompat.h', - 'internal.h', - 'purple.h', - 'purpleenums.h', - 'purpleprivate.h', -] - -# Extra options to supply to gtkdoc-scan. -scan_args = [ - '--deprecated-guards=PURPLE_DISABLE_DEPRECATED', - '--rebuild-types', - '--rebuild-sections', - '--ignore-headers=' + ' '.join(ignore_hfiles), -] - -# Extra options to supply to gtkdoc-mkdb. -mkdb_args = [ - '--ignore-files=' + ' '.join(ignore_hfiles), -] - -# Extra options to supply to gtkdoc-fixxref -fixxref_args = [ +libpurple_doc_content_files = [ + 'code_contributions.md', + 'mercurial.md', + 'plugin_i18n.md', + 'plugin_ids.md', + 'signals_account.md', + 'signals_blist.md', + 'signals_cmd.md', + 'signals_connection.md', + 'signals_conversation.md', + 'signals_core.md', + 'signals_jabber.md', + 'signals_notify.md', + 'signals_savedstatus.md', + 'signals_xfer.md', + 'tut_c_plugins.md', ] -libpurple_version_xml = configure_file( - input : 'version.xml.in', - output : 'version.xml', - configuration : version_conf) +if get_option('doc') + libpurple_toml = configure_file( + input : 'libpurple.toml.in', + output : 'libpurple.toml', + configuration : version_conf, + install : true, + install_dir : docs_dir / 'libpurple', + ) -content_files = [ - 'plugin_i18n.xml', - 'plugin_ids.xml', - 'signals_account.xml', - 'signals_blist.xml', - 'signals_certificate.xml', - 'signals_cmd.xml', - 'signals_connection.xml', - 'signals_conversation.xml', - 'signals_core.xml', - 'signals_jabber.xml', - 'signals_log.xml', - 'signals_notify.xml', - 'signals_plugin.xml', - 'signals_savedstatus.xml', - 'signals_xfer.xml', - 'tut_c_plugins.xml', - 'tut_signals.xml', - 'ui_ops.xml', -] + libpurple_doc = custom_target('libpurple-doc', + input : [ libpurple_toml, libpurple_gir[0] ], + output : 'libpurple', + command : [ + gidocgen, + 'generate', + '--quiet', + '--fatal-warnings', + '--config=@INPUT0@', + '--output-dir=@OUTPUT@', + '--no-namespace-dir', + '--content-dir=@0@'.format(meson.current_source_dir()), + '--add-include-path=@0@'.format(meson.global_build_root() / 'subprojects/gplugin/gplugin'), + '@INPUT1@' + ], + depend_files : [ libpurple_doc_content_files ], + build_by_default : true, + install : true, + install_dir : docs_dir, + ) +endif -libpurple_doc = gnome.gtkdoc(DOC_MODULE, - main_xml : DOC_MODULE + '-docs.xml', - src_dir : libpurple_inc, - dependencies : libpurple_dep, - install : true, - scan_args : scan_args, - mkdb_args : mkdb_args, - fixxref_args: fixxref_args, - gobject_typesfile : DOC_MODULE + '.types', - content_files : content_files) diff --git a/doc/reference/libpurple/plugin_i18n.md b/doc/reference/libpurple/plugin_i18n.md new file mode 100644 index 0000000000..cfe724a2d7 --- /dev/null +++ b/doc/reference/libpurple/plugin_i18n.md @@ -0,0 +1,140 @@ +Title: Third Party Plugin Translation +Slug: 3rd-party-plugin-i18n + +## Third Party Plugin Translation + +### Introduction + +For the purpose of this document we're going to assume that your plugin: + +* Is set up to use autotools. It may be possible to add translation support +without autotools, but we have no idea how. We may not want to know, either ;) +* Has an autogen.sh. You may have also called this bootstrap.sh or similar. +* Resides in a source tree that has `configure.ac` and `Makefile.am` in the +top-level directory as well as a `src` directory in which the plugin's source +is located. A `Makefile.am` should also exist in the `src` directory. + +### Steps To Follow + +For a plugin to have translation support there are a few steps that need to +followed: + +* In your `autogen.sh`, add the following after your other utility checks: + +```sh +(intltoolize --version) < /dev/null > /dev/null 2>&1 || { + echo; + echo "You must have intltool installed to compile <YOUR PLUGIN NAME>"; + echo; + exit; +} +``` + +* Then before your call to aclocal add: + +```sh +intltoolize --force --copy +``` + +* Now edit `configure.ac` and add the following: + +```m4 +AC_PROG_INTLTOOL + +GETTEXT_PACKAGE=<YOUR PLUGIN NAME> +AC_SUBST(GETTEXT_PACKAGE) +AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], [Define the gettext package to be used]) + +ALL_LINGUAS="" +AM_GLIB_GNU_GETTEXT +``` + +The position of these macros in the file don't really matter, but if you +have issues either play around with it or feel free to ask one of the Pidgin +developers. Finally add `po/Makefile.in` to you `AC_OUTPUT` command. + +* Now create a directory named 'po'. + +* `cd` into the `po` directory. + +* Create/edit the file `POTFILES.in` in your favorite editor. Each line +should be the name of a file that could or does have strings marked for +translating (we're getting to that step). These file names should be +relative to the top directory of your plugin's source tree. + +* `cd` back to the top directory of your plugin's source tree. + +* Open `Makefile.am` and add `po` to your `SUBDIRS` variable. + +* While still in the top directory of your plugin's source tree, execute +`intltool-prepare`. This will setup anything extra that intltool needs. + +* Fire off `autogen.sh` and when it's completed, verify that you have a +`po/POTFILES` (notice the lack of a .in). If you do, everything should be +set on the autotools side. + +* Take a break, stretch your legs, smoke a cigarette, whatever, because +we're done with the autotools part. + +* When you're ready, `cd` into the directory with the source files for your +plugin. + +* Open the file containing the `plugin_query` function. + +* If you're not already, please make sure that you are including the +`config.h` file for you plugin. Note that `config.h` could be whatever +you told autohead to use with AM_CONFIG_HEADER. Also add the following: + +```c +#include <glib/gi18n-lib.h> +``` + +Make sure that this include is after you include of your `config.h`, +otherwise you will break your build. Also note that if you wish to +maintain compatibility with older versions of GLib, you will need to +include additional preprocessor directives, which we won't cover here. + +* This is where things get a bit goofy. libpurple is going to try to +translate our strings using the libpurple gettext package. So we have to +convert them before libpurple attempts to. + +* To do this, we're going to change the entries for `name`, `summary`, and +`description` to `NULL`. + +* Next, locate your `plugin_load` function. Your name for this function will be +the first parameter to `GPLUGIN_NATIVE_PLUGIN_DECLARE()` plus `_load`. + +* Now add the following within your 'plugin_load' function: + +```c + bindtextdomain(GETTEXT_PACKAGE, PURPLE_LOCALEDIR); + bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8"); + + info.name = _("<YOUR PLUGIN NAME>"); + info.summary = _("<YOUR PLUGIN SUMMARY>"); + info.description = _("<YOUR PLUGIN DESCRIPTION>"); +``` + +> Note that the `_()` is intentional, and that it is telling intltool that +> this string should be translated. There is also `N_()` which says that a +> string should only be marked for translation but should not be translated +> yet. + +* Go through the rest of your code and mark all the other strings for +translation with `_()`. + +* When thats done, feel free to commit your work, create your po template +(pot file) or whatever. + +* To create you po template, `cd` to `po` and execute: + +```sh +intltool-update --pot +``` + +* To add new translations to your plugin, all you have to do is add the +language code to the `ALL_LINGUAS` variable in your `configure.ac`. Take +note that this list of languages should be separated by a space. After +you have added the language code to `ALL_LINGUAS`, drop the `xx.po` file +into `po`, and re-`autogen.sh`. After a full build you should now be +able to use the translation. diff --git a/doc/reference/libpurple/plugin_i18n.xml b/doc/reference/libpurple/plugin_i18n.xml deleted file mode 100644 index 5b145bc2f9..0000000000 --- a/doc/reference/libpurple/plugin_i18n.xml +++ /dev/null @@ -1,175 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-plugin-i18n"> - <title>Third Party Plugin Translation</title> - - <sect2 id="plugin-i18n-introduction"> - <title>Introduction</title> - - <para> - For the purpose of this document we're going to assume that your plugin: - - <itemizedlist> - <listitem><para> -Is set up to use autotools. It may be possible to add translation support -without autotools, but we have no idea how. We may not want to know, either ;) - </para></listitem> - <listitem><para> -Has an autogen.sh. You may have also called this bootstrap.sh or similar. - </para></listitem> - <listitem><para> -Resides in a source tree that has <literal>configure.ac</literal> and -<literal>Makefile.am</literal> in the top-level directory as well as a -<literal>src</literal> directory in which the plugin's source is located. A -<literal>Makefile.am</literal> should also exist in the <literal>src</literal> -directory. - </para></listitem> - </itemizedlist> - </para> - </sect2> - - <sect2 id="plugin-i18n-steps"> - <title>Steps to follow</title> - - <para> - For a plugin to have translation support there are a few steps that need to - followed: - - <itemizedlist> - <listitem><para> -In your autogen.sh, add the following after your other utility checks: -<programlisting> -(intltoolize --version) < /dev/null > /dev/null 2>&1 || { - echo; - echo "You must have intltool installed to compile <YOUR PLUGIN NAME>"; - echo; - exit; -} -</programlisting> -Then before your call to aclocal add: -<programlisting> -intltoolize --force --copy -</programlisting> - </para></listitem> - <listitem><para> -Now edit configure.ac and add the following: -<programlisting> -AC_PROG_INTLTOOL - -GETTEXT_PACKAGE=<YOUR PLUGIN NAME> -AC_SUBST(GETTEXT_PACKAGE) -AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], [Define the gettext package to be used]) - -ALL_LINGUAS="" -AM_GLIB_GNU_GETTEXT -</programlisting> -The position of these macros in the file don't really matter, but if you -have issues either play around with it or feel free to ask one of the Pidgin -developers. Finally add 'po/Makefile.in' to you 'AC_OUTPUT' command. - </para></listitem> - <listitem><para> -Now create a directory named 'po'. - </para></listitem> - <listitem><para> -'cd' into the 'po' directory. - </para></listitem> - <listitem><para> -Create/edit the file 'POTFILE.in' in your favorite editor. Each line -should be the name of a file that could or does have strings marked for -translating (we're getting to that step). These file names should be -relative to the top directory of your plugin's source tree. - </para></listitem> - <listitem><para> -'cd' back to the top directory of your plugin's source tree. - </para></listitem> - <listitem><para> -Open 'Makefile.am' and add 'po' to your 'SUBDIRS' variable. - </para></listitem> - <listitem><para> -While still in the top directory of your plugin's source tree, execute -'intltool-prepare'. This will setup anything extra that intltool needs. - </para></listitem> - <listitem><para> -Fire off 'autogen.sh' and when it's completed, verify that you have a -'po/POTFILES' (notice the lack of a .in). If you do, everything should be -set on the autotools side. - </para></listitem> - <listitem><para> -Take a break, stretch your legs, smoke a cigarette, whatever, because -we're done with the autotools part. - </para></listitem> - <listitem><para> -When you're ready, 'cd' into the directory with the source files for your -plugin. - </para></listitem> - <listitem><para> -Open the file containing the 'plugin_query' function. - </para></listitem> - <listitem><para> -If you're not already, please make sure that you are including the -'config.h' file for you plugin. Note that 'config.h' could be whatever -you told autohead to use with AM_CONFIG_HEADER. Also add the following: -<programlisting> -#include <glib/gi18n-lib.h> -</programlisting> -Make sure that this include is after you include of your 'config.h', -otherwise you will break your build. Also note that if you wish to -maintain compatibility with older versions of GLib, you will need to -include additional preprocessor directives, which we won't cover here. - </para></listitem> - <listitem><para> -This is where things get a bit goofy. libpurple is going to try to -translate our strings using the libpurple gettext package. So we have to -convert them before libpurple attempts to. - </para></listitem> - <listitem><para> -To do this, we're going to change the entries for name, summary, and -description to NULL. - </para></listitem> - <listitem><para> -Next, locate your 'plugin_load' function. Your name for this function will be -the first parameter to GPLUGIN_NATIVE_PLUGIN_DECLARE() plus '_load'. - </para></listitem> - <listitem><para> -Now add the following within your 'plugin_load' function: -<programlisting> - bindtextdomain(GETTEXT_PACKAGE, PURPLE_LOCALEDIR); - bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8"); - - info.name = _("<YOUR PLUGIN NAME>"); - info.summary = _("<YOUR PLUGIN SUMMARY>"); - info.description = _("<YOUR PLUGIN DESCRIPTION>"); -</programlisting> -Note that the _() is intentional, and that it is telling intltool that -this string should be translated. There is also N_() which says that a -string should only be marked for translation but should not be translated -yet. - </para></listitem> - <listitem><para> -Go through the rest of your code and mark all the other strings for -translation with _(). - </para></listitem> - <listitem><para> -When thats done, feel free to commit your work, create your po template -(pot file) or whatever. - </para></listitem> - <listitem><para> -To create you po template, 'cd' to 'po' and execute: -<programlisting> -intltool-update --pot -</programlisting> - </para></listitem> - <listitem><para> -To add new translations to your plugin, all you have to do is add the -language code to the 'ALL_LINGUAS' variable in your configure.ac. Take -note that this list of languages should be separated by a space. After -you have added the language code to 'ALL_LINGUAS', drop the xx.po file -into 'po', and re-'autogen.sh'. After a full build you should now be -able to use the translation. - </para></listitem> - </itemizedlist> - </para> - </sect2> -</chapter> diff --git a/doc/reference/libpurple/plugin_ids.md b/doc/reference/libpurple/plugin_ids.md new file mode 100644 index 0000000000..160635cfd1 --- /dev/null +++ b/doc/reference/libpurple/plugin_ids.md @@ -0,0 +1,107 @@ +Title: Plugin IDs +Slug: plugin-ids + +## Plugin IDs + +### Introduction + +Every plugin contains a unique identifier. Third-party plugins (that is, +plugins written by anyone who is not a libpurple, Pidgin, or Finch developer) +are expected to use a plugin ID that follows a specific format. This format +categorizes plugins and makes duplicate IDs highly unlikely. + +### Format + +The basic format of a plugin ID is as follows: + +``` +type-username-pluginname +``` + +The ***type*** indicator specifies the type of plugin. This must be one +of the following: + +#### Types Of Plugins + +core +: A core libpurple plugin, capable of being loaded in any program using +libpurple. Core plugins may not contain any UI-specific code. + +prpl +: A protocol plugin. This is a core plugin which provides libpurple the ability +to connect to another IM or chat network. + +gtk +: A GTK+ (a.k.a. Pidgin) plugin. These plugins may use GTK+ code, but may not +use window toolkit code, such as X11, Win32, Cocoa, or Carbon. + +gtk-x11 +: A GTK+ plugin that uses X11 code. These plugins may use both GTK+ code and +X11 code, allowing to hook into features specific to X11. + +gtk-win32 +: A GTK+ plugin that uses Win32 code. These plugins may use both GTK+ code and +Win32 code, allowing to hook into features available on Windows. + +gnt +: A GNT (a.k.a. Finch) plugin. These plugins may use GNT code. + +The ***username*** must be a unique identifier for you. It +***should*** be your https://developer.pidgin.im Trac user ID. Failing that, you +could use your SourceForge user ID or your Libera.chat IRC nickname, if you +have either. The https://developer.pidgin.im Trac user ID is preferred. +Do ***not*** leave this field blank! + +The ***pluginname*** is the name of your plugin. It is usually all +lowercase letters and matches the static plugin ID (the first argument to +the GPLUGIN_NATIVE_PLUGIN_DECLARE() macro call), although it can be anything you +like. Do ***not*** include version information in the plugin ID--the +`PurplePluginInfo` object already has a property for this. + +### One Last Rule For Plugin IDs + +Plugin IDs may ***NOT*** contain spaces. If you need a space, use another +hyphen (-). + +### Exceptions To The Rule + +As with any rule there are exceptions. If you browse through the source +tree you will see that the plugins we distribute with the Pidgin source +do not contain a username field. This is because while one developer may +have written each specific plugin, the plugins are maintained +collectively by the entire development team. This lack of a username +field is also an indicator that the plugin is one of our plugins and not +a third-party plugin. + +Another exception to the rule is the +[Purple Plugin Pack](https://keep.imfreedom.org/pidgin/purple-plugin-pack/). +All plugins whose lives started in the Purple Plugin Pack use +`"plugin_pack"` for the username field to indicate origination in +the Purple Plugin Pack. + +These two exceptions are mentioned here for completeness. We don't +encourage breaking the conventions set forth by the rules outlined above. + +### Examples Of Well-Chosen Plugin IDs + +The following is a list of well-chosen Plugin IDs listing a few good examples. + +gtk-amc_grim-guifications +: This is the plugin ID for the Guifications 2.x plugin. + +gtk-rlaager-album +: This is the plugin ID for the Album plugin, which is now part of the +Purple Plugin Pack. Its ID follows the rules because its life started prior +to its inclusion in the Plugin Pack. + +core-rlaager-irchelper +: This is the plugin ID for the IRC Helper plugin, which is now part of the +Purple Plugin Pack. Its ID follows the rules because its life started prior +to its inclusion in the Plugin Pack. + +### Plugin Database + +Although it doesn't exist yet, in time there will be a plugin database +on the Pidgin website, where users can download and install new plugins. +Plugins will be accessed by your plugin ID, which is one reason why it +must be unique. diff --git a/doc/reference/libpurple/plugin_ids.xml b/doc/reference/libpurple/plugin_ids.xml deleted file mode 100644 index d301126472..0000000000 --- a/doc/reference/libpurple/plugin_ids.xml +++ /dev/null @@ -1,191 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-plugin-ids"> - <title>Plugin IDs</title> - - <sect2 id="plugin-ids-introduction"> - <title>Introduction</title> - <para> -Every plugin contains a unique identifier. Third-party plugins (that is, -plugins written by anyone who is not a libpurple, Pidgin, or Finch developer) -are expected to use a plugin ID that follows a specific format. This format -categorizes plugins and makes duplicate IDs highly unlikely. - </para> - </sect2> - - <sect2 id="plugin-ids-format"> - <title>Format</title> - <para> -The basic format of a plugin ID is as follows: - -<programlisting> -type-username-pluginname -</programlisting> - </para> - - <para> -The <emphasis>type</emphasis> indicator specifies the type of plugin. This must be one -of the following: - - <table> - <title>Types of plugins</title> - <tgroup cols="2"> - <colspec colwidth="*" colnum="1" align="left"/> - <colspec colwidth="*" colnum="2" align="left"/> - <thead> - <row> -<entry><emphasis>type</emphasis></entry> -<entry>description</entry> - </row> - </thead> - <tbody> - <row> -<entry><literal>core</literal></entry> -<entry> -A core libpurple plugin, capable of being loaded in any program using libpurple. -Core plugins may not contain any UI-specific code. -</entry> - </row> - <row> -<entry><literal>prpl</literal></entry> -<entry> -A protocol plugin. This is a core plugin which provides libpurple the ability to -connect to another IM or chat network. -</entry> - </row> - <row> -<entry><literal>gtk</literal></entry> -<entry> -A GTK+ (a.k.a. Pidgin) plugin. These plugins may use GTK+ code, but may not use -window toolkit code, such as X11, Win32, Cocoa, or Carbon. -</entry> - </row> - <row> -<entry><literal>gtk-x11</literal></entry> -<entry> -A GTK+ plugin that uses X11 code. These plugins may use both GTK+ code and X11 -code, allowing to hook into features specific to X11. -</entry> - </row> - <row> -<entry><literal>gtk-win32</literal></entry> -<entry> -A GTK+ plugin that uses Win32 code. These plugins may use both GTK+ code and -Win32 code, allowing to hook into features available on Windows. -</entry> - </row> - <row> -<entry><literal>gnt</literal></entry> -<entry> -A GNT (a.k.a. Finch) plugin. These plugins may use GNT code. -</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - - <para> -The <emphasis>username</emphasis> must be a unique identifier for you. It -<emphasis>should</emphasis> be your https://developer.pidgin.im Trac user ID. Failing that, you -could use your SourceForge user ID or your Libera.chat IRC nickname, if you -have either. The https://developer.pidgin.im Trac user ID is preferred. -Do <emphasis>not</emphasis> leave this field blank! - </para> - - <para> -The <emphasis>pluginname</emphasis> is the name of your plugin. It is usually all -lowercase letters and matches the static plugin ID (the first argument to -the GPLUGIN_NATIVE_PLUGIN_DECLARE() macro call), although it can be anything you -like. Do <emphasis>not</emphasis> include version information in the plugin ID--the -<literal>PurplePluginInfo</literal> object already has a property for this. - </para> - </sect2> - - <sect2 id="plugin-ids-nospaces"> - <title>One Last Rule for Plugin IDs</title> - <para> -Plugin IDs may <emphasis>NOT</emphasis> contain spaces. If you need a space, use another -hyphen (-). - </para> - </sect2> - - <sect2 id="plugin-ids-exceptions"> - <title>Exceptions to the Rule</title> - <para> -As with any rule there are exceptions. If you browse through the source -tree you will see that the plugins we distribute with the Pidgin source -do not contain a username field. This is because while one developer may -have written each specific plugin, the plugins are maintained -collectively by the entire development team. This lack of a username -field is also an indicator that the plugin is one of our plugins and not -a third-party plugin. - -Another exception to the rule is the <ulink -url="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin -Pack</ulink>. All plugins whose lives started in the Purple Plugin Pack use -<literal>"plugin_pack"</literal> for the username field to indicate origination in -the Purple Plugin Pack. - -These two exceptions are mentioned here for completeness. We don't -encourage breaking the conventions set forth by the rules outlined above. - </para> - </sect2> - - <sect2 id="plugin-ids-examples"> - <title>Examples of Well-Chosen Plugin IDs</title> - <para> -The following is a list of well-chosen Plugin IDs listing a few good examples. - - <table> - <title>Examples</title> - <tgroup cols="2"> - <colspec colwidth="*" colnum="1" align="left"/> - <colspec colwidth="*" colnum="2" align="left"/> - <thead> - <row> -<entry>id</entry> -<entry>description</entry> - </row> - </thead> - <tbody> - <row> -<entry><literal>"gtk-amc_grim-guifications"</literal></entry> -<entry> -This is the plugin ID for the Guifications 2.x plugin. -</entry> - </row> - <row> -<entry><literal>"gtk-rlaager-album"</literal></entry> -<entry> -This is the plugin ID for the Album plugin, which is now part of the -Purple Plugin Pack. Its ID follows the rules because its life started prior -to its inclusion in the Plugin Pack. -</entry> - </row> - <row> -<entry><literal>"core-rlaager-irchelper"</literal></entry> -<entry> -This is the plugin ID for the IRC Helper plugin, which is now part of the -Purple Plugin Pack. Its ID follows the rules because its life started prior -to its inclusion in the Plugin Pack. -</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - </sect2> - - <sect2 id="plugin-ids-plugin-db"> - <title>Plugin Database</title> - <para> -Although it doesn't exist yet, in time there will be a plugin database -on the Pidgin website, where users can download and install new plugins. -Plugins will be accessed by your plugin ID, which is one reason why it -must be unique. - </para> - </sect2> -</chapter> diff --git a/doc/reference/libpurple/signals_account.md b/doc/reference/libpurple/signals_account.md new file mode 100644 index 0000000000..8482dc7a1f --- /dev/null +++ b/doc/reference/libpurple/signals_account.md @@ -0,0 +1,450 @@ +Title: Account Signals +Slug: account-signals + +## Account Signals + +### Signal List + +* [account-created](#account-created) +* [account-destroying](#account-destroying) +* [account-added](#account-added) +* [account-connecting](#account-connecting) +* [account-removed](#account-removed) +* [account-disabled](#account-disabled) +* [account-enabled](#account-enabled) +* [account-setting-info](#account-setting-info) +* [account-set-info](#account-set-info) +* [account-status-changed](#account-status-changed) +* [account-actions-changed](#account-actions-changed) +* [account-alias-changed](#account-alias-changed) +* [account-authorization-requested](#account-authorization-requested) +* [account-authorization-denied](#account-authorization-denied) +* [account-authorization-granted](#account-authorization-granted) +* [account-error-changed](#account-error-changed) +* [account-signed-on](#account-signed-on) +* [account-signed-off](#account-signed-off) +* [account-connection-error](#account-connection-error) + +### Signal Details + +#### account-created + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when an account is created by calling purple_account_new. + +**Parameters:** + +**account** +: The account. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-destroying + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when an account is about to be destroyed. + +**Parameters:** + +**account** +: The account. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-added + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when an account is added. + +**Parameters:** + + +**account** +: The account that was added. See `purple_accounts_add()`. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-connecting + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +This is emitted when an account is in the process of connecting. + +**Parameters:** + +**account** +: The account in the process of connecting. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-removed + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when an account is removed. + +**Parameters:** + +**account** +: The account that was removed. See `purple_accounts_remove()`. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-disabled + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when an account is disabled. + +**Parameters:** + +**account** +: The account that was disabled. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-enabled + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when an account is enabled. + +**Parameters**: + +**account** +: The account that was enabled. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-setting-info + +```c +void user_function(PurpleAccount *account, const gchar *new_info, gpointer user_data); +``` + +Emitted when a user is about to send his new user info, or profile, to the server. + +**Parameters:** + +**account** +: The account that the info will be set on. + +**new_info** +: The new information to set. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-set-info + +```c +void user_function(PurpleAccount *account, const gchar *new_info, gpointer user_data); +``` + +Emitted when a user sent his new user info, or profile, to the server. + +**Parameters:** + +**account** +: The account that the info was set on. + +**new_info** +: The new information set. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-status-changed + +```c +void user_function(PurpleAccount *account, + PurpleStatus *old, + PurpleStatus *new, + gpointer user_data); +``` + +Emitted when the status of an account changes (after the change). + +**Parameters:** + +**account** +: The account that changed status. + +**old** +: The status before change. + +**new** +: The status after change. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-actions-changed + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when the account actions are changed after initial connection. + +**Parameters:** + +**account** +: The account whose actions changed. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-alias-changed + +```c +void user_function(PurpleAccount *account, const gchar *old, gpointer user_data); +``` + +Emitted when the alias of an account changes (after the change). + +**Parameters:** + +**account** +: The account for which the alias was changed. + +**old** +: The alias before change. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-authorization-requested + +```c +int user_function(PurpleAccount *account, + const gchar *user, + const gchar *message, + gchar **response, + gpointer user_data); +``` + +Emitted when a user requests authorization. + +**Parameters:** + +**account** +: The account. + +**user** +: The name of the user requesting authorization. + +**message** +: The authorization request message. + +**response** +: The message to send in the response. + +**user_data** +: User data set when the signal handler was connected. + +**Returns:** + +`PURPLE_ACCOUNT_RESPONSE_IGNORE` +: To silently ignore the request + +`PURPLE_ACCOUNT_RESPONSE_DENY` +: To block the request (the sender might get informed) + +`PURPLE_ACCOUNT_RESPONSE_ACCEPT` +: If the request should be granted. + +`PURPLE_ACCOUNT_RESPONSE_PASS` +: The user will be prompted with the request. + +---- + +#### account-authorization-denied + +```c +void user_function(PurpleAccount *account, + const gchar *user, + const gchar *message, + gpointer user_data); +``` + +Emitted when the authorization request for a buddy is denied. + +**Parameters:** + +**account** +: The account. + +**user** +: The name of the user requesting authorization. + +**message** +: The message to tell the buddy who was denied. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-authorization-granted + +```c +void user_function(PurpleAccount *account, + const gchar *user, + const gchar *message, + gpointer user_data); +``` + +Emitted when the authorization request for a buddy is granted. + +**Paramaters:** + +**account** +: The account. + +**user** +: The name of the user requesting authorization. + +**message** +: The message to tell the buddy who was granted authorization. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-error-changed + +```c +void user_function(PurpleAccount *account, + const PurpleConnectionErrorInfo *old_error, + const PurpleConnectionErrorInfo *current_error, + gpointer user_data); +``` + +Emitted when `account`'s error changes. You should not call purple_account_clear_current_error() while this signal is being emitted. + +**Parameters:** + +**account** +: The account whose error has changed. + +**old_error** +: The account's previous error, or `NULL` if it had no error. After this signal is emitted, `old_error` is not guaranteed to be a valid pointer. + +**new_error** +: The account's new error, or `NULL` if it has no error. If not `NULL`, `new_error` will remain a valid until pointer just after the next time this signal is emitted for this `account`. See `purple_account_get_current_error()`. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-signed-on + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when an account has signed on. + +**Parameters:** + +**account** +: The account that has signed on. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-signed-off + +```c +void user_function(PurpleAccount *account, gpointer user_data); +``` + +Emitted when an account has signed off. + +**Parameters:** + +**account** +: The account that has signed off. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### account-connection-error + +```c +void user_function(PurpleAccount *account, + PurpleConnectionError err, + const gchar *desc, + gpointer user_data) +``` + +Emitted when a connection error occurs, before `"signed"`-off. + +**Parameters:** + +**account** +: The account on which the error has occurred. + +**err** +: The error that occurred. + +**desc** +: A description of the error, giving more information. + +**user_data** +: User data set when the signal handler was connected. diff --git a/doc/reference/libpurple/signals_account.xml b/doc/reference/libpurple/signals_account.xml deleted file mode 100644 index 910efc85bb..0000000000 --- a/doc/reference/libpurple/signals_account.xml +++ /dev/null @@ -1,521 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-account"> -<title>Account signals</title> - -<refsect1 id="accounts.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="accounts-account-created">account-created</link>" - "<link linkend="accounts-account-destroying">account-destroying</link>" - "<link linkend="accounts-account-added">account-added</link>" - "<link linkend="accounts-account-connecting">account-connecting</link>" - "<link linkend="accounts-account-removed">account-removed</link>" - "<link linkend="accounts-account-disabled">account-disabled</link>" - "<link linkend="accounts-account-enabled">account-enabled</link>" - "<link linkend="accounts-account-setting-info">account-setting-info</link>" - "<link linkend="accounts-account-set-info">account-set-info</link>" - "<link linkend="accounts-account-status-changed">account-status-changed</link>" - "<link linkend="accounts-account-actions-changed">account-actions-changed</link>" - "<link linkend="accounts-account-alias-changed">account-alias-changed</link>" - "<link linkend="accounts-account-authorization-requested">account-authorization-requested</link>" - "<link linkend="accounts-account-authorization-denied">account-authorization-denied</link>" - "<link linkend="accounts-account-authorization-granted">account-authorization-granted</link>" - "<link linkend="accounts-account-error-changed">account-error-changed</link>" - "<link linkend="accounts-account-signed-on">account-signed-on</link>" - "<link linkend="accounts-account-signed-off">account-signed-off</link>" - "<link linkend="accounts-account-connection-error">account-connection-error</link>" -</synopsis> -</refsect1> - -<refsect1 id="accounts.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="accounts-account-created" role="signal"> - <title>The <literal>"account-created"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when an account is created by calling purple_account_new. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-destroying" role="signal"> - <title>The <literal>"account-destroying"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when an account is about to be destroyed. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-added" role="signal"> - <title>The <literal>"account-added"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when an account is added. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that was added. See <literal>purple_accounts_add</literal>.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-connecting" role="signal"> - <title>The <literal>"account-connecting"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -This is called when an account is in the process of connecting. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account in the process of connecting.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-removed" role="signal"> - <title>The <literal>"account-removed"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when an account is removed. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that was removed. See <literal>purple_accounts_remove</literal>.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-disabled" role="signal"> - <title>The <literal>"account-disabled"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when an account is disabled. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that was disabled.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-enabled" role="signal"> - <title>The <literal>"account-enabled"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when an account is enabled. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that was enabled.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-setting-info" role="signal"> - <title>The <literal>"account-setting-info"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *new_info, - gpointer user_data) -</programlisting> - <para> -Emitted when a user is about to send his new user info, or profile, to the server. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that the info will be set on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>new_info</parameter> :</term> - <listitem><simpara>The new information to set.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-set-info" role="signal"> - <title>The <literal>"account-set-info"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *new_info, - gpointer user_data) -</programlisting> - <para> -Emitted when a user sent his new user info, or profile, to the server. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that the info was set on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>new_info</parameter> :</term> - <listitem><simpara>The new information set.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-status-changed" role="signal"> - <title>The <literal>"account-status-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - PurpleStatus *old, - PurpleStatus *new, - gpointer user_data) -</programlisting> - <para> -Emitted when the status of an account changes (after the change). - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that changed status.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>old</parameter> :</term> - <listitem><simpara>The status before change.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>new</parameter> :</term> - <listitem><simpara>The status after change.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-actions-changed" role="signal"> - <title>The <literal>"account-actions-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when the account actions are changed after initial connection. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account whose actions changed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-alias-changed" role="signal"> - <title>The <literal>"account-alias-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *old, - gpointer user_data) -</programlisting> - <para> -Emitted when the alias of an account changes (after the change). - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account for which the alias was changed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>old</parameter> :</term> - <listitem><simpara>The alias before change.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-authorization-requested" role="signal"> - <title>The <literal>"account-authorization-requested"</literal> signal</title> -<programlisting> -int user_function (PurpleAccount *account, - const char *user, - const char *message, - char **response, - gpointer user_data) -</programlisting> - <para> -Emitted when a user requests authorization. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user</parameter> :</term> - <listitem><simpara>The name of the user requesting authorization.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The authorization request message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>response</parameter> :</term> - <listitem><simpara>The message to send in the response.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>PURPLE_ACCOUNT_RESPONSE_IGNORE to silently ignore the request, PURPLE_ACCOUNT_RESPONSE_DENY to block the request (the sender might get informed), PURPLE_ACCOUNT_RESPONSE_ACCEPT if the request should be granted. If PURPLE_ACCOUNT_RESPONSE_PASS is returned, then the user will be prompted with the request.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-authorization-denied" role="signal"> - <title>The <literal>"account-authorization-denied"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *user, - const char *message, - gpointer user_data) -</programlisting> - <para> -Emitted when the authorization request for a buddy is denied. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user</parameter> :</term> - <listitem><simpara>The name of the user requesting authorization.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message to tell the buddy who was denied.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-authorization-granted" role="signal"> - <title>The <literal>"account-authorization-granted"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *user, - const char *message, - gpointer user_data) -</programlisting> - <para> -Emitted when the authorization request for a buddy is granted. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user</parameter> :</term> - <listitem><simpara>The name of the user requesting authorization.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message to tell the buddy who was granted authorization.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-error-changed" role="signal"> - <title>The <literal>"account-error-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const PurpleConnectionErrorInfo *old_error, - const PurpleConnectionErrorInfo *current_error, - gpointer user_data) -</programlisting> - <para> -Emitted when <literal>account</literal>'s error changes. You should not call purple_account_clear_current_error() while this signal is being emitted. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account whose error has changed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>old_error</parameter> :</term> - <listitem><simpara>The account's previous error, or <literal>NULL</literal> if it had no error. After this signal is emitted, <literal>old_error</literal> is not guaranteed to be a valid pointer.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>new_error</parameter> :</term> - <listitem><simpara>The account's new error, or <literal>NULL</literal> if it has no error. If not <literal>NULL</literal>, <literal>new_error</literal> will remain a valid until pointer just after the next time this signal is emitted for this <literal>account</literal>. See <literal>purple_account_get_current_error</literal>().</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-signed-on" role="signal"> - <title>The <literal>"account-signed-on"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when an account has signed on. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that has signed on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-signed-off" role="signal"> - <title>The <literal>"account-signed-off"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - gpointer user_data) -</programlisting> - <para> -Emitted when an account has signed off. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account that has signed off.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="accounts-account-connection-error" role="signal"> - <title>The <literal>"account-connection-error"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *gc, - PurpleConnectionError err, - const gchar *desc, - gpointer user_data) -</programlisting> - <para> -Emitted when a connection error occurs, before <literal>"signed"</literal>-off. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account on which the error has occurred.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>err</parameter> :</term> - <listitem><simpara>The error that occurred.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>desc</parameter> :</term> - <listitem><simpara>A description of the error, giving more information.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_blist.md b/doc/reference/libpurple/signals_blist.md new file mode 100644 index 0000000000..7dbb5ccdc0 --- /dev/null +++ b/doc/reference/libpurple/signals_blist.md @@ -0,0 +1,225 @@ +Title: Buddy List Signals +Slug: buddy-list-signals + +## Buddy List Signals + +### Signal List + +* [buddy-status-changed](#buddy-status-changed) +* [buddy-idle-changed](#buddy-idle-changed) +* [buddy-signed-on](#buddy-signed-on) +* [buddy-signed-off](#buddy-signed-off) +* [update-idle](#update-idle) +* [blist-node-extended-menu](#blist-node-extended-menu) +* [buddy-icon-changed](#buddy-icon-changed) +* [blist-node-aliased](#blist-node-aliased) +* [buddy-caps-changed](#buddy-caps-changed) +* [ui-caps-changed](#ui-caps-changed) + +### Signal Details + +#### buddy-status-changed + +```c +void user_function(PurpleBuddy *buddy, + PurpleStatus *old_status, + PurpleStatus *status, + gpointer user_data); +``` + +Emitted when a buddy on your buddy list goes away. + +**Parameters:** + +**buddy** +: The buddy whose status changed. + +**old_status** +: The status that the buddy just changed from. + +**status** +: The status that the buddy just changed to. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### buddy-idle-changed + +```c +void user_function(PurpleBuddy *buddy, + gboolean old_idle, + gboolean idle, + gpointer user_data); +``` + +Emitted when a buddy on your buddy list becomes idle. + +**Parameters:** + +**buddy** +: The buddy whose idle status changed. + +**old_idle** +: Whether the buddy was idle. + +**idle** +: Whether the buddy is currently idle. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### buddy-signed-on + +```c +void user_function(PurpleBuddy *buddy, gpointer user_data); +``` + +Emitted when a buddy on your buddy list signs on. + +**Parameters:** + +**buddy** +: The buddy that signed on. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### buddy-signed-off + +```c +void user_function(PurpleBuddy *buddy, gpointer user_data); +``` + +Emitted when a buddy on your buddy list signs off. + +**Parameters:** + +**buddy** +: The buddy that signed off. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### update-idle + +```c +void user_function(gpointer user_data); +``` + +Emitted when the buddy list is refreshed and the idle times are updated. + +**Parameters:** + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### blist-node-extended-menu + +```c +void user_function(PurpleBlistNode *node, GList **menu, gpointer user_data); +``` + +Emitted when a buddylist menu is being constructed `menu` is a pointer to a +GList of PurpleMenuAction's allowing a plugin to add menu items. + +---- + +#### blist-node-added + +```c +void user_function(PurpleBlistNode *node, gpointer user_data); +``` + +Emitted when a new blist node is added to the buddy list. + +---- + +#### blist-node-removed + +```c +void user_function(PurpleBlistNode *node, gpointer user_data); +``` + +Emitted when a blist node is removed from the buddy list. + +---- + +#### buddy-icon-changed + +```c +void user_function(PurpleBuddy *buddy, gpointer user_data); +``` + +Emitted when a buddy's icon is set. + +---- + +#### blist-node-aliased + +```c +void user_function(PurpleBlistNode *node, + const gchar *old_alias, + gpointer user_data); +``` + +Emitted when a blist node (buddy, chat, or contact) is aliased. + +---- + +#### buddy-caps-changed + +```c +void user_function(PurpleBuddy *buddy, + PurpleMediaCaps newcaps, + PurpleMediaCaps oldcaps, + gpointer user_data); +``` + +Emitted when updating a buddy's media capabilities. + +**Parameters:** + +**buddy** +: The buddy. + +**newcaps** +: . + +**oldcaps** +: . + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### ui-caps-changed + +```c +void user_function(PurpleMediaCaps newcaps, + PurpleMediaCaps oldcaps, + gpointer user_data); +``` + +Emitted when updating the media capabilities of the UI. + +**Parameters:** + +**newcaps** +: . + +**oldcaps** +: . + +**user_data** +: user data set when the signal handler was connected. diff --git a/doc/reference/libpurple/signals_blist.xml b/doc/reference/libpurple/signals_blist.xml deleted file mode 100644 index 5483ca3878..0000000000 --- a/doc/reference/libpurple/signals_blist.xml +++ /dev/null @@ -1,263 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-blist"> -<title>Buddy List signals</title> - -<refsect1 id="blist.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="blist-buddy-status-changed">buddy-status-changed</link>" - "<link linkend="blist-buddy-idle-changed">buddy-idle-changed</link>" - "<link linkend="blist-buddy-signed-on">buddy-signed-on</link>" - "<link linkend="blist-buddy-signed-off">buddy-signed-off</link>" - "<link linkend="blist-update-idle">update-idle</link>" - "<link linkend="blist-blist-node-extended-menu">blist-node-extended-menu</link>" - "<link linkend="blist-buddy-icon-changed">buddy-icon-changed</link>" - "<link linkend="blist-blist-node-aliased">blist-node-aliased</link>" - "<link linkend="blist-buddy-caps-changed">buddy-caps-changed</link>" - "<link linkend="blist-ui-caps-changed">ui-caps-changed</link>" -</synopsis> -</refsect1> - -<refsect1 id="blist.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="blist-buddy-status-changed" role="signal"> - <title>The <literal>"buddy-status-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleBuddy *buddy, - PurpleStatus *old_status, - PurpleStatus *status, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy on your buddy list goes away. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>buddy</parameter> :</term> - <listitem><simpara>The buddy whose status changed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>old_status</parameter> :</term> - <listitem><simpara>The status that the buddy just changed from.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>status</parameter> :</term> - <listitem><simpara>The status that the buddy just changed to.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="blist-buddy-idle-changed" role="signal"> - <title>The <literal>"buddy-idle-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleBuddy *buddy, - gboolean old_idle, - gboolean idle, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy on your buddy list becomes idle. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>buddy</parameter> :</term> - <listitem><simpara>The buddy whose idle status changed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>old_idle</parameter> :</term> - <listitem><simpara>Whether the buddy was idle.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>idle</parameter> :</term> - <listitem><simpara>Whether the buddy is currently idle.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="blist-buddy-signed-on" role="signal"> - <title>The <literal>"buddy-signed-on"</literal> signal</title> -<programlisting> -void user_function (PurpleBuddy *buddy, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy on your buddy list signs on. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>buddy</parameter> :</term> - <listitem><simpara>The buddy that signed on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="blist-buddy-signed-off" role="signal"> - <title>The <literal>"buddy-signed-off"</literal> signal</title> -<programlisting> -void user_function (PurpleBuddy *buddy, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy on your buddy list signs off. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>buddy</parameter> :</term> - <listitem><simpara>The buddy that signed off.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="blist-update-idle" role="signal"> - <title>The <literal>"update-idle"</literal> signal</title> -<programlisting> -void user_function (gpointer user_data) -</programlisting> - <para> -Emitted when the buddy list is refreshed and the idle times are updated. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="blist-blist-node-extended-menu" role="signal"> - <title>The <literal>"blist-node-extended-menu"</literal> signal</title> -<programlisting> -void user_function (PurpleBlistNode *node, - GList **menu, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddlist menu is being constructed <literal>menu</literal> is a pointer to a GList of PurpleMenuAction's allowing a plugin to add menu items. - </para> -</refsect2> - -<refsect2 id="blist-blist-node-added" role="signal"> - <title>The <literal>"blist-node-added"</literal> signal</title> -<programlisting> -void user_function (PurpleBlistNode *node, - gpointer user_data) -</programlisting> - <para> -Emitted when a new blist node is added to the buddy list. - </para> -</refsect2> - -<refsect2 id="blist-blist-node-removed" role="signal"> - <title>The <literal>"blist-node-removed"</literal> signal</title> -<programlisting> -void user_function (PurpleBlistNode *node, - gpointer user_data) -</programlisting> - <para> -Emitted when a blist node is removed from the buddy list. - </para> -</refsect2> - -<refsect2 id="blist-buddy-icon-changed" role="signal"> - <title>The <literal>"buddy-icon-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleBuddy *buddy, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy's icon is set. - </para> -</refsect2> - -<refsect2 id="blist-blist-node-aliased" role="signal"> - <title>The <literal>"blist-node-aliased"</literal> signal</title> -<programlisting> -void user_function (PurpleBlistNode *node, - const char *old_alias, - gpointer user_data) -</programlisting> - <para> -Emitted when a blist node (buddy, chat, or contact) is aliased. - </para> -</refsect2> - -<refsect2 id="blist-buddy-caps-changed" role="signal"> - <title>The <literal>"buddy-caps-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleBuddy *buddy, - PurpleMediaCaps newcaps, - PurpleMediaCaps oldcaps, - gpointer user_data) -</programlisting> - <para> -Emitted when updating a buddy's media capabilities. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>buddy</parameter> :</term> - <listitem><simpara>The buddy.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>newcaps</parameter> :</term> - <listitem><simpara>.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>oldcaps</parameter> :</term> - <listitem><simpara>.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="blist-ui-caps-changed" role="signal"> - <title>The <literal>"ui-caps-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleMediaCaps newcaps, - PurpleMediaCaps oldcaps, - gpointer user_data) -</programlisting> - <para> -Emitted when updating the media capabilities of the UI. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>newcaps</parameter> :</term> - <listitem><simpara>.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>oldcaps</parameter> :</term> - <listitem><simpara>.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_certificate.xml b/doc/reference/libpurple/signals_certificate.xml deleted file mode 100644 index 8ba6ea71b4..0000000000 --- a/doc/reference/libpurple/signals_certificate.xml +++ /dev/null @@ -1,65 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-certificate"> -<title>Certificate signals</title> - -<refsect1 id="certificates.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="certificates-certificate-stored">certificate-stored</link>" - "<link linkend="certificates-certificate-deleted">certificate-deleted</link>" -</synopsis> -</refsect1> - -<refsect1 id="certificates.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="certificates-certificate-stored" role="signal"> - <title>The <literal>"certificate-stored"</literal> signal</title> -<programlisting> -void user_function (PurpleCertificatePool *pool, - const gchar *id, - gpointer data) -</programlisting> - <para> -Emitted when a pool stores a certificate. Connect to the pool instance. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>pool</parameter> :</term> - <listitem><simpara>Pool the certificate has been stored into.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>id</parameter> :</term> - <listitem><simpara>Key the certificate was stored under.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="certificates-certificate-deleted" role="signal"> - <title>The <literal>"certificate-deleted"</literal> signal</title> -<programlisting> -void user_function (PurpleCertificatePool *pool, - const gchar *id, - gpointer data) -</programlisting> - <para> -Emitted when a pool deletes a certificate. Connect to the pool instance. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>pool</parameter> :</term> - <listitem><simpara>Pool the certificate was deleted from.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>id</parameter> :</term> - <listitem><simpara>Key that was deleted.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_cmd.md b/doc/reference/libpurple/signals_cmd.md new file mode 100644 index 0000000000..1236567405 --- /dev/null +++ b/doc/reference/libpurple/signals_cmd.md @@ -0,0 +1,54 @@ +Title: Command Signals +Slug: command-signals + +## Command Signals + +### Signal List + +* [cmd-added](#cmd-added) +* [cmd-removed](#cmd-removed) + +### Signal Details + +#### cmd-added + +```c +void user_function(const gchar *command, + PurpleCmdPriority priority, + PurpleCmdFlag flag, + gpointer user_data); +``` + +Emitted when a new command is added. + +**Parameters:** + +**command** +: The new command. + +**priority** +: The priority of the new command. + +**flag** +: The command flags. + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### cmd-removed + +```c +void user_function(const gchar *command, gpointer user_data); +``` + +Emitted when a command is removed. + +**Parameters:** + +**command** +: The removed command. + +**user_data** +: User data set when the signal handler was connected. diff --git a/doc/reference/libpurple/signals_cmd.xml b/doc/reference/libpurple/signals_cmd.xml deleted file mode 100644 index c3fd0d0eab..0000000000 --- a/doc/reference/libpurple/signals_cmd.xml +++ /dev/null @@ -1,73 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-cmd"> -<title>Command signals</title> - -<refsect1 id="cmds.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="cmds-cmd-added">cmd-added</link>" - "<link linkend="cmds-cmd-removed">cmd-removed</link>" -</synopsis> -</refsect1> - -<refsect1 id="cmds.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="cmds-cmd-added" role="signal"> - <title>The <literal>"cmd-added"</literal> signal</title> -<programlisting> -void user_function (const char *command, - PurpleCmdPriority priority, - PurpleCmdFlag flag, - gpointer user_data) -</programlisting> - <para> -Emitted when a new command is added. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>command</parameter> :</term> - <listitem><simpara>The new command.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>priority</parameter> :</term> - <listitem><simpara>The priority of the new command.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flag</parameter> :</term> - <listitem><simpara>The command flags.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="cmds-cmd-removed" role="signal"> - <title>The <literal>"cmd-removed"</literal> signal</title> -<programlisting> -void user_function (const char *command, - gpointer user_data) -</programlisting> - <para> -Emitted when a command is removed. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>command</parameter> :</term> - <listitem><simpara>The removed command.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_connection.md b/doc/reference/libpurple/signals_connection.md new file mode 100644 index 0000000000..552dd425b6 --- /dev/null +++ b/doc/reference/libpurple/signals_connection.md @@ -0,0 +1,173 @@ +Title: Connection Signals +Slug: connection-signals + +## Connection Signals + +### Signal List + +* [online](#online) +* [offline](#offline) +* [signing-on](#signing-on) +* [signed-on](#signed-on) +* [autojoin](#autojoin) +* [signing-off](#signing-off) +* [signed-off](#signed-off) +* [connection-error](#connection-error) + +### Signal Details + +#### online + +```c +void user_function(gpointer user_data); +``` + +Emitted when the first connection has connected when all connections were +previously not connected. + +**Parameters:** + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### offline + +```c +void user_function(gpointer user_data); +``` + +Emitted when the last connected connection has disconnected. + + +**Parameters:** + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### signing-on + +```c +void user_function(PurpleConnection *gc, gpointer user_data); +``` + +Emitted when a connection is about to sign on. + +**Parameters:** + +**gc** +: The connection that is about to sign on. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### signed-on + +```c +void user_function(PurpleConnection *gc, gpointer user_data); +``` + +Emitted when a connection has signed on. + +**Parameters:** + +**gc** +: The connection that has signed on. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### autojoin + +```c +gboolean user_function(PurpleConnection *gc, gpointer user_data); +``` + +Emitted when a connection has signed on, after the signed-on signal, to signal +UIs to autojoin chats if they wish. UIs should connect to this with +`PURPLE_SIGNAL_PRIORITY_HIGHEST` to allow plugins to block this signal before +the UI sees it and then re-emit it later. + +**Parameters:** + +**gc** +: The connection that has signed on. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the signal was handled or `FALSE` otherwise. In practice, the return +value is irrelevant, as it really only exists so plugins can block the UI's +autojoin. + +---- + +#### signing-off + +```c +void user_function(PurpleConnection *gc, gpointer user_data); +``` + +Emitted when a connection is about to sign off. + +**Parameters:** + +**gc** +: The connection that is about to sign off. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### signed-off + +```c +void user_function(PurpleConnection *gc, gpointer user_data); +``` + +Emitted when a connection has signed off. + +**Parameters:** + +**gc** +: The connection that has signed off. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### connection-error + +```c +void user_function(PurpleConnection *gc, + PurpleConnectionError err, + const gchar *desc, + gpointer user_data); +``` + +Emitted when a connection error occurs, before `"signed"`-off. + +**Parameters:** + +**gc** +: The connection on which the error has occurred. + +**err** +: The error that occurred. + +**desc** +: A description of the error, giving more information. + +**user_data** +: user data set when the signal handler was connected. diff --git a/doc/reference/libpurple/signals_connection.xml b/doc/reference/libpurple/signals_connection.xml deleted file mode 100644 index 50635f904a..0000000000 --- a/doc/reference/libpurple/signals_connection.xml +++ /dev/null @@ -1,200 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-connection"> -<title>Connection signals</title> - -<refsect1 id="connections.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="connections-online">online</link>" - "<link linkend="connections-offline">offline</link>" - "<link linkend="connections-signing-on">signing-on</link>" - "<link linkend="connections-signed-on">signed-on</link>" - "<link linkend="connections-autojoin">autojoin</link>" - "<link linkend="connections-signing-off">signing-off</link>" - "<link linkend="connections-signed-off">signed-off</link>" - "<link linkend="connections-connection-error">connection-error</link>" -</synopsis> -</refsect1> - -<refsect1 id="connections.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="connections-online" role="signal"> - <title>The <literal>"online"</literal> signal</title> -<programlisting> -void user_function (gpointer user_data) -</programlisting> - <para> -Emitted when the first connection has connected when all connections were -previously not connected. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="connections-offline" role="signal"> - <title>The <literal>"online"</literal> signal</title> -<programlisting> -void user_function (gpointer user_data) -</programlisting> - <para> -Emitted when the last connected connection has disconnected. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="connections-signing-on" role="signal"> - <title>The <literal>"signing-on"</literal> signal</title> -<programlisting> -void user_function (PurpleConnection *gc, - gpointer user_data) -</programlisting> - <para> -Emitted when a connection is about to sign on. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection that is about to sign on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="connections-signed-on" role="signal"> - <title>The <literal>"signed-on"</literal> signal</title> -<programlisting> -void user_function (PurpleConnection *gc, - gpointer user_data) -</programlisting> - <para> -Emitted when a connection has signed on. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection that has signed on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="connections-autojoin" role="signal"> - <title>The <literal>"autojoin"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleConnection *gc, - gpointer user_data) -</programlisting> - <para> -Emitted when a connection has signed on, after the signed-on signal, to signal UIs to autojoin chats if they wish. UIs should connect to this with <literal>PURPLE_SIGNAL_PRIORITY_HIGHEST</literal> to allow plugins to block this signal before the UI sees it and then re-emit it later. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection that has signed on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>TRUE</literal> if the signal was handled or <literal>FALSE</literal> otherwise. In practice, the return value is irrelevant, as it really only exists so plugins can block the UI's autojoin.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="connections-signing-off" role="signal"> - <title>The <literal>"signing-off"</literal> signal</title> -<programlisting> -void user_function (PurpleConnection *gc, - gpointer user_data) -</programlisting> - <para> -Emitted when a connection is about to sign off. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection that is about to sign off.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="connections-signed-off" role="signal"> - <title>The <literal>"signed-off"</literal> signal</title> -<programlisting> -void user_function (PurpleConnection *gc, - gpointer user_data) -</programlisting> - <para> -Emitted when a connection has signed off. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection that has signed off.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="connections-connection-error" role="signal"> - <title>The <literal>"connection-error"</literal> signal</title> -<programlisting> -void user_function (PurpleConnection *gc, - PurpleConnectionError err, - const gchar *desc, - gpointer user_data) -</programlisting> - <para> -Emitted when a connection error occurs, before <literal>"signed"</literal>-off. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection on which the error has occurred.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>err</parameter> :</term> - <listitem><simpara>The error that occurred.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>desc</parameter> :</term> - <listitem><simpara>A description of the error, giving more information.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_conversation.md b/doc/reference/libpurple/signals_conversation.md new file mode 100644 index 0000000000..6d29fd5580 --- /dev/null +++ b/doc/reference/libpurple/signals_conversation.md @@ -0,0 +1,1066 @@ +Title: Conversation Signals +Slug: conversation-signals + +## Conversation Signals + +### Signal List + +* [writing-im-msg](#writing-im-msg) +* [wrote-im-msg](#wrote-im-msg) +* [sending-im-msg](#sending-im-msg) +* [sent-im-msg](#sent-im-msg) +* [receiving-im-msg](#receiving-im-msg) +* [received-im-msg](#received-im-msg) +* [blocked-im-msg](#blocked-im-msg) +* [writing-chat-msg](#writing-chat-msg) +* [wrote-chat-msg](#wrote-chat-msg) +* [sending-chat-msg](#sending-chat-msg) +* [sent-chat-msg](#sent-chat-msg) +* [receiving-chat-msg](#receiving-chat-msg) +* [received-chat-msg](#received-chat-msg) +* [conversation-created](#conversation-created) +* [conversation-updated](#conversation-updated) +* [deleting-conversation](#deleting-conversation) +* [buddy-typing](#buddy-typing) +* [buddy-typing-stopped](#buddy-typing-stopped) +* [chat-user-joining](#chat-user-joining) +* [chat-user-joined](#chat-user-joined) +* [chat-user-flags](#chat-user-flags) +* [chat-user-leaving](#chat-user-leaving) +* [chat-user-left](#chat-user-left) +* [chat-inviting-user](#chat-inviting-user) +* [chat-invited-user](#chat-invited-user) +* [chat-invited](#chat-invited) +* [chat-invite-blocked](#chat-invite-blocked) +* [chat-joined](#chat-joined) +* [chat-join-failed](#chat-join-failed) +* [chat-left](#chat-left) +* [chat-topic-changed](#chat-topic-changed) +* [cleared-message-history](#cleared-message-history) +* [conversation-extended-menu](#conversation-extended-menu) +* [sent-attention](#sent-attention) +* [got-attention](#got-attention) + +### Signal Details + +#### writing-im-msg + +```c +gboolean user_function(PurpleAccount *account, + const gchar *who, + gchar **message, + PurpleIMConversation *im, + PurpleMessageFlags flags, + gpointer user_data); +``` + +Emitted before a message is written in an IM conversation. If the message is changed, then the changed message is displayed and logged instead of the original message. + +> Make sure to free `*message` before you replace it. + +**Parameters:** + +**account** +: The account. + +**who** +: The name of the user. + +**message** +: A pointer to the message. + +**im** +: The IM conversation. + +**flags** +: Flags for this message. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** +`TRUE` if the message should be canceled, or `FALSE` otherwise. + +---- + +#### wrote-im-msg + +```c +void user_function(PurpleAccount *account, + const gchar *who, + gchar *message, + PurpleIMConversation *im, + PurpleMessageFlags flags, + gpointer user_data); +``` + +Emitted after a message is written and possibly displayed in a conversation. + +**Parameters:** + +**account** +: The account. + +**who** +: The name of the user. + +**message** +: The message. + +**im** +: The IM conversation. + +**flags** +: Flags for this message. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### sending-im-msg + +```c +void user_function(PurpleAccount *account, + const gchar *receiver, + gchar **message, + gpointer user_data); +``` + +Emitted before sending an IM to a user. `message` is a pointer to the message +string, so the plugin can replace the message before being sent. + +> Make sure to free `*message` before you replace it! + +**Parameters:** + +**account** +: The account the message is being sent on. + +**receiver** +: The username of the receiver. + +**message** +: A pointer to the outgoing message. This can be modified. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### sent-im-msg + +```c +void user_function(PurpleAccount *account, + const gchar *receiver, + const gchar *message, + gpointer user_data); +``` + +Emitted after sending an IM to a user. + +**Parameters:** + +**account** +: The account the message was sent on. + +**receiver** +: The username of the receiver. + +**message** +: The message that was sent. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### receiving-im-msg + +```c +gboolean user_function(PurpleAccount *account, + gchar **sender, + gchar **message, + PurpleIMConversation *im, + PurpleMessageFlags *flags, + gpointer user_data) +``` + +Emitted when an IM is received. The callback can replace the name of the sender, the message, or the flags by modifying the pointer to the strings and integer. This can also be used to cancel a message by returning `TRUE`. + +> Make sure to free `*sender` and `*message` before you replace them! + +**Parameters:** + +**account** +: The account the message was received on. + +**sender** +: A pointer to the username of the sender. + +**message** +: A pointer to the message that was sent. + +**im** +: The IM conversation. + +**flags** +: A pointer to the IM message flags. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the message should be canceled, or `FALSE` otherwise. + +---- + +#### received-im-msg + +```c +void user_function(PurpleAccount *account, + gchar *sender, + gchar *message, + PurpleIMConversation *im, + PurpleMessageFlags flags, + gpointer user_data); +``` + +Emitted after an IM is received. + +**Parameters:** + +**account** +: The account the message was received on. + +**sender** +: The username of the sender. + +**message** +: The message that was sent. + +**im** +: The IM conversation. + +**flags** +: The IM message flags. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### blocked-im-msg + +```c +void user_function(PurpleAccount *account, + const gchar *sender, + const gchar *message, + PurpleMessageFlags flags, + time_t when, + gpointer user_data); +``` + +Emitted after an IM is blocked due to privacy settings. + +**Parameters:** + +**account** +: The account the message was received on. + +**sender** +: The username of the sender. + +**message** +: The message that was blocked. + +**flags** +: The IM message flags. + +**when** +: The time the message was sent. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### writing-chat-msg + +```c +gboolean user_function(PurpleAccount *account, + const gchar *who, + gchar **message, + PurpleChatConversation *chat, + PurpleMessageFlags flags, + gpointer user_data); +``` + +Emitted before a message is written in a chat conversation. If the message is changed, then the changed message is displayed and logged instead of the original message. + +> Make sure to free `*message` before you replace it! + +**Parameters:** + +**account** +: The account. + +**who** +: The name of the user. + +**message** +: A pointer to the message. + +**chat** +: The chat conversation. + +**flags** +: Flags for this message. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the message should be canceled, or `FALSE` otherwise. + +---- + +#### wrote-chat-msg + +```c +void user_function(PurpleAccount *account, + const gchar *who, + gchar *message, + PurpleChatConversation *chat, + PurpleMessageFlags flags, + gpointer user_data); +``` + +Emitted after a message is written and possibly displayed in a chat. + +**Parameters:** + +**account** +: The account. + +**who** +: The name of the user. + +**message** +: The message. + +**chat** +: The chat conversation. + +**flags** +: Flags for this message. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### sending-chat-msg + +```c +void user_function(PurpleAccount *account, + gchar **message, + gint id, + gpointer user_data); +``` + +Emitted before sending a message to a chat. `message` is a pointer to the +message string, so the plugin can replace the message before being sent. + +> Make sure to free `*message` before you replace it! + +**Parameters:** + +**account** +: The account the message is being sent on. + +**message** +: A pointer to the message that will be sent. + +**id** +: The ID of the chat. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### sent-chat-msg + +```c +void user_function(PurpleAccount *account, + const gchar *message, + gint id, + gpointer user_data) +``` + +Emitted after sending a message to a chat. + +**Parameters:** + +**account** +: The account the message was sent on. + +**message** +: The message that was sent. + +**id** +: The ID of the chat. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### receiving-chat-msg + +```c +gboolean user_function(PurpleAccount *account, + gchar **sender, + gchar **message, + PurpleChatConversation *chat, + gint *flags, + gpointer user_data); +``` + +Emitted when a chat message is received. The callback can replace the name of the sender, the message, or the flags by modifying the pointer to the strings. This can also be used to cancel displaying a message by returning `TRUE`. + +> Make sure to free `*sender` and `*message` before you replace them! + +**Parameters:** + +**account** +: The account the message was received on. + +**sender** +: A pointer to the username of the sender. + +**message** +: A pointer to the message that was sent. + +**chat** +: The chat conversation. + +**flags** +: A pointer to the chat message flags. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the message should be canceled, or `FALSE` otherwise. + +---- + +#### received-chat-msg + +```c +void user_function(PurpleAccount *account, + gchar *sender, + gchar *message, + PurpleChatConversation *chat, + PurpleMessageFlags flags, + gpointer user_data) +``` + +Emitted after a chat message is received. + +**Parameters:** + +**account** +: The account the message was received on. + +**sender** +: The username of the sender. + +**message** +: The message that was sent. + +**chat** +: The chat conversation. + +**flags** +: The chat message flags. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### conversation-created + +```c +void user_function(PurpleConversation *conv, gpointer user_data); +``` + +Emitted when a new conversation is created. + +**Parameters:** + +**conv** +: The new conversation. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### conversation-updated + +```c +void user_function(PurpleConversation *conv, + PurpleConvUpdateType type, + gpointer user_data); +``` + +Emitted when a conversation is updated. + +**Parameters:** + +**conv** +: The conversation that was updated. + +**type** +: The type of update that was made. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### deleting-conversation + +```c +void user_function(PurpleConversation *conv, gpointer user_data); +``` + +Emitted just before a conversation is to be destroyed. + +**Parameters:** + +**conv** +: The conversation that's about to be destroyed. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### buddy-typing + +```c +void user_function(PurpleAccount *account, + const gchar *name, + gpointer user_data); +``` + +Emitted when a buddy starts typing in a conversation window. + +**Parameters:** + +**account** +: The account of the user which is typing. + +**name** +: The name of the user which is typing. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### buddy-typing-stopped + +```c +void user_function(PurpleAccount *account, + const gchar *name, + gpointer user_data); +``` + +Emitted when a buddy stops typing in a conversation window. + +**Parameters:** + +**account** +: The account of the user which stopped typing. + +**name** +: The name of the user which stopped typing. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-user-joining + +```c +gboolean user_function(PurpleChatConversation *chat, + const gchar *name, + PurpleChatUserFlags flags, + gpointer user_data); +``` + +Emitted when a buddy is joining a chat, before the list of users in the chat updates to include the new user. + +**Parameters:** + +**chat** +: The chat conversation. + +**name** +: The name of the user that is joining the conversation. + +**flags** +: The flags of the user that is joining the conversation. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the join should be hidden, or `FALSE` otherwise. + +---- + +#### chat-user-joined + +```c +void user_function(PurpleChatConversation *chat, + const gchar *name, + PurpleChatUserFlags flags, + gboolean new_arrival, + gpointer user_data); +``` + +Emitted when a buddy joined a chat, after the users list is updated. + +**Parameters:** + +**chat** +: The chat conversation. + +**name** +: The name of the user that has joined the conversation. + +**flags** +: The flags of the user that has joined the conversation. + +**new_arrival** +: If the buddy is a new arrival. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-join-failed + +```c +void user_function(PurpleConnection *gc, + GHashTable *components, + gpointer user_data); +``` + +Emitted when an account fails to join a chat room. + +**Parameters:** + +**gc** +: The PurpleConnection of the account which failed to join the chat. + +**data** +: The components passed to purple_serv_join_chat() originally. The hash function should be g_str_hash() and the equal function should be g_str_equal(). + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-user-flags + +```c +void user_function(PurpleChatUser *chatuser, + PurpleChatUserFlags oldflags, + PurpleChatUserFlags newflags, + gpointer user_data); +``` + +Emitted when a user in a chat changes flags. + +**Parameters:** + +**chatuser** +: The chat user whose flags changed. + +**oldflags** +: The old flags. + +**newflags** +: The new flags. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-user-leaving + +```c +gboolean user_function(PurpleChatConversation *chat, + const gchar *name, + const gchar *reason, + gpointer user_data); +``` + +Emitted when a user is leaving a chat, before the user list is updated. This +may include an optional reason why the user is leaving. + +**Parameters:** + +**chat** +: The chat conversation. + +**name** +: The name of the user that is leaving the chat. + +**reason** +: The optional reason why the user is leaving. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the leave should be hidden, or `FALSE` otherwise. + +---- + +#### chat-user-left + + +```c +void user_function(PurpleChatConversation *chat, + const gchar *name, + const gchar *reason, + gpointer user_data); +``` + +Emitted when a user leaves a chat, after the user list is updated. This may include an optional reason why the user is leaving. + +**Parameters:** + +**chat** +: The chat conversation. + +**name** +: The name of the user that left the chat. + +**reason** +: The optional reason why the user left the chat. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-inviting-user + + +```c +void user_function(PurpleChatConversation *chat, + const gchar *name, + gchar **invite_message, + gpointer user_data); +``` + +Emitted when a user is being invited to the chat. The callback can replace the invite message to the invitee by modifying the pointer to the invite message. + +> Make sure to free `*invite_message` before you replace it! + +**Parameters:** + +**chat** +: The chat conversation. + +**name** +: The name of the user being invited. + +**invite_message** +: A pointer to the reason why a user is being invited. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-invited-user + +```c +void user_function(PurpleChatConversation *conv, + const gchar *name, + const gchar *invite_message, + gpointer user_data); +``` + +Emitted when a user invited another user to a chat. + +**Parameters:** + +**chat** +: The chat conversation. + +**name** +: The name of the user that was invited. + +**invite_message** +: The message to be sent to the user when invited. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-invited + +```c +gint user_function(PurpleAccount *account, + const gchar *inviter, + const gchar *chat, + const gchar *invite_message, + GHashTable *components, + gpointer user_data); +``` + +Emitted when an account was invited to a chat. + +**Parameters:** + +**account** +: The account being invited. + +**inviter** +: The username of the person inviting the account. + +**chat** +: The name of the chat you're being invited to. + +**invite_message** +: The optional invite message. + +**components** +: The components necessary if you want to call purple_serv_join_chat(). + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +Less than zero if the invitation should be rejected, greater than zero if the +invitation should be accepted. If zero is returned, the default behavior will +be maintained: the user will be prompted. + +---- + +#### chat-invite-blocked + +```c +void user_function(PurpleAccount *account, + const gchar *inviter, + const gchar *name, + const gchar *message, + GHashTable *data); +``` + +Emitted when an invitation to join a chat is blocked. + +**Parameters:** + +**account** +: The account the invitation was sent to. + +**inviter** +: The name of the person sending the invitation. + +**name** +: The name of the chat invited to. + +**message** +: The invitation message sent. + +**data** +: Hashtable containing data about the invited chat. + +---- + +#### chat-joined + +```c +void user_function(PurpleChatConversation *chat, gpointer user_data); +``` + +Emitted when an account joins a chat room. + +**Parameters:** + +**chat** +: The conversation that joined the chat room. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-left + +```c +void user_function(PurpleChatConversation *chat, gpointer user_data); +``` + +Emitted when an account leaves a chat room. + +**Parameters:** + +**chat** +: The conversation that left the chat room. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### chat-topic-changed + +```c +void user_function(PurpleChatConversation *chat, + const gchar *who, + const gchar *topic, + gpointer user_data); +``` + +Emitted when the topic is changed in a chat. + +**Parameters:** + +**chat** +: The chat conversation whose topic changed. + +**who** +: The name of the person that changed the topic. + +**topic** +: The new topic. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### conversation-extended-menu + +```c +void user_function(PurpleConversation *conv, + GList **list, + gpointer user_data); +``` + +Emitted when the UI requests a list of plugin actions for a conversation. + +**Parameters:** + +**conv** +: The conversation. + +**list** +: A pointer to the list of actions. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### cleared-message-history + +```c +void user_function(PurpleConversation *conv, gpointer user_data); +``` + +Emitted when the conversation history is cleared. + +**Parameters:** + +**conv** +: The conversation. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### sent-attention + +```c +void user_function(PurpleAccount *account, + const gchar *who, + PurpleConversation *conv, + guint type, + gpointer user_data); +``` + +Emitted when receiving an attention message (buzz, nudge, etc.). + +**Parameters:** + +**account** +: The account. + +**who** +: The name of the person receiving the attention. + +**conv** +: The conversation. + +**type** +: The attention type (an index starting at 0). + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### got-attention + +```c +void user_function(PurpleAccount *account, + const gchar *who, + PurpleConversation *conv, + guint type, + gpointer user_data); +``` + +Emitted when receiving an attention message (buzz, nudge, etc.). + +**Parameters:** + +**account** +: The account. + +**who** +: The name of the person sending the attention. + +**conv** +: The conversation. + +**type** +: The attention type (an index starting at 0). + +**user_data** +: user data set when the signal handler was connected. diff --git a/doc/reference/libpurple/signals_conversation.xml b/doc/reference/libpurple/signals_conversation.xml deleted file mode 100644 index b5d5b5ee4e..0000000000 --- a/doc/reference/libpurple/signals_conversation.xml +++ /dev/null @@ -1,1232 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-conversation"> -<title>Conversation signals</title> - -<refsect1 id="conversations.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="conversations-writing-im-msg">writing-im-msg</link>" - "<link linkend="conversations-wrote-im-msg">wrote-im-msg</link>" - "<link linkend="conversations-sending-im-msg">sending-im-msg</link>" - "<link linkend="conversations-sent-im-msg">sent-im-msg</link>" - "<link linkend="conversations-receiving-im-msg">receiving-im-msg</link>" - "<link linkend="conversations-received-im-msg">received-im-msg</link>" - "<link linkend="conversations-blocked-im-msg">blocked-im-msg</link>" - "<link linkend="conversations-writing-chat-msg">writing-chat-msg</link>" - "<link linkend="conversations-wrote-chat-msg">wrote-chat-msg</link>" - "<link linkend="conversations-sending-chat-msg">sending-chat-msg</link>" - "<link linkend="conversations-sent-chat-msg">sent-chat-msg</link>" - "<link linkend="conversations-receiving-chat-msg">receiving-chat-msg</link>" - "<link linkend="conversations-received-chat-msg">received-chat-msg</link>" - "<link linkend="conversations-conversation-created">conversation-created</link>" - "<link linkend="conversations-conversation-updated">conversation-updated</link>" - "<link linkend="conversations-deleting-conversation">deleting-conversation</link>" - "<link linkend="conversations-buddy-typing">buddy-typing</link>" - "<link linkend="conversations-buddy-typing-stopped">buddy-typing-stopped</link>" - "<link linkend="conversations-chat-user-joining">chat-user-joining</link>" - "<link linkend="conversations-chat-user-joined">chat-user-joined</link>" - "<link linkend="conversations-chat-user-flags">chat-user-flags</link>" - "<link linkend="conversations-chat-user-leaving">chat-user-leaving</link>" - "<link linkend="conversations-chat-user-left">chat-user-left</link>" - "<link linkend="conversations-chat-inviting-user">chat-inviting-user</link>" - "<link linkend="conversations-chat-invited-user">chat-invited-user</link>" - "<link linkend="conversations-chat-invited">chat-invited</link>" - "<link linkend="conversations-chat-invite-blocked">chat-invite-blocked</link>" - "<link linkend="conversations-chat-joined">chat-joined</link>" - "<link linkend="conversations-chat-join-failed">chat-join-failed</link>" - "<link linkend="conversations-chat-left">chat-left</link>" - "<link linkend="conversations-chat-topic-changed">chat-topic-changed</link>" - "<link linkend="conversations-cleared-message-history">cleared-message-history</link>" - "<link linkend="conversations-conversation-extended-menu">conversation-extended-menu</link>" - "<link linkend="conversations-sent-attention">sent-attention</link>" - "<link linkend="conversations-got-attention">got-attention</link>" -</synopsis> -</refsect1> - -<refsect1 id="conversations.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="conversations-writing-im-msg" role="signal"> - <title>The <literal>"writing-im-msg"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleAccount *account, - const char *who, - char **message, - PurpleIMConversation *im, - PurpleMessageFlags flags, - gpointer user_data) -</programlisting> - <para> -Emitted before a message is written in an IM conversation. If the message is changed, then the changed message is displayed and logged instead of the original message. - </para> - <note><para> -Make sure to free <literal>*message</literal> before you replace it! - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>who</parameter> :</term> - <listitem><simpara>The name of the user.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>A pointer to the message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>im</parameter> :</term> - <listitem><simpara>The IM conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>Flags for this message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-wrote-im-msg" role="signal"> - <title>The <literal>"wrote-im-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *who, - char *message, - PurpleIMConversation *im, - PurpleMessageFlags flags, - gpointer user_data) -</programlisting> - <para> -Emitted after a message is written and possibly displayed in a conversation. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>who</parameter> :</term> - <listitem><simpara>The name of the user.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>im</parameter> :</term> - <listitem><simpara>The IM conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>Flags for this message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-sending-im-msg" role="signal"> - <title>The <literal>"sending-im-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *receiver, - char **message, - gpointer user_data) -</programlisting> - <para> -Emitted before sending an IM to a user. <literal>message</literal> is a pointer to the message string, so the plugin can replace the message before being sent. - </para> - <note><para> -Make sure to free <literal>*message</literal> before you replace it! - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message is being sent on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>receiver</parameter> :</term> - <listitem><simpara>The username of the receiver.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>A pointer to the outgoing message. This can be modified.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-sent-im-msg" role="signal"> - <title>The <literal>"sent-im-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *receiver, - const char *message, - gpointer user_data) -</programlisting> - <para> -Emitted after sending an IM to a user. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message was sent on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>receiver</parameter> :</term> - <listitem><simpara>The username of the receiver.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message that was sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-receiving-im-msg" role="signal"> - <title>The <literal>"receiving-im-msg"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleAccount *account, - char **sender, - char **message, - PurpleIMConversation *im, - PurpleMessageFlags *flags, - gpointer user_data) -</programlisting> - <para> -Emitted when an IM is received. The callback can replace the name of the sender, the message, or the flags by modifying the pointer to the strings and integer. This can also be used to cancel a message by returning <literal>TRUE</literal>. - </para> - <note><para> -Make sure to free <literal>*sender</literal> and <literal>*message</literal> before you replace them! - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message was received on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>sender</parameter> :</term> - <listitem><simpara>A pointer to the username of the sender.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>A pointer to the message that was sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>im</parameter> :</term> - <listitem><simpara>The IM conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>A pointer to the IM message flags.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-received-im-msg" role="signal"> - <title>The <literal>"received-im-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - char *sender, - char *message, - PurpleIMConversation *im, - PurpleMessageFlags flags, - gpointer user_data) -</programlisting> - <para> -Emitted after an IM is received. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message was received on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>sender</parameter> :</term> - <listitem><simpara>The username of the sender.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message that was sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>im</parameter> :</term> - <listitem><simpara>The IM conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>The IM message flags.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-blocked-im-msg" role="signal"> - <title>The <literal>"blocked-im-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *sender, - const char *message, - PurpleMessageFlags flags, - time_t when, - gpointer user_data) -</programlisting> - <para> -Emitted after an IM is blocked due to privacy settings. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message was received on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>sender</parameter> :</term> - <listitem><simpara>The username of the sender.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message that was blocked.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>The IM message flags.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>when</parameter> :</term> - <listitem><simpara>The time the message was sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-writing-chat-msg" role="signal"> - <title>The <literal>"writing-chat-msg"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleAccount *account, - const char *who, - char **message, - PurpleChatConversation *chat, - PurpleMessageFlags flags, - gpointer user_data) -</programlisting> - <para> -Emitted before a message is written in a chat conversation. If the message is changed, then the changed message is displayed and logged instead of the original message. - </para> - <note><para> -Make sure to free <literal>*message</literal> before you replace it! - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>who</parameter> :</term> - <listitem><simpara>The name of the user.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>A pointer to the message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>Flags for this message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-wrote-chat-msg" role="signal"> - <title>The <literal>"wrote-chat-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *who, - char *message, - PurpleChatConversation *chat, - PurpleMessageFlags flags, - gpointer user_data) -</programlisting> - <para> -Emitted after a message is written and possibly displayed in a chat. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>who</parameter> :</term> - <listitem><simpara>The name of the user.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>Flags for this message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-sending-chat-msg" role="signal"> - <title>The <literal>"sending-chat-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - char **message, - int id, - gpointer user_data) -</programlisting> - <para> -Emitted before sending a message to a chat. <literal>message</literal> is a pointer to the message string, so the plugin can replace the message before being sent. - </para> - <note><para> -Make sure to free <literal>*message</literal> before you replace it! - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message is being sent on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>A pointer to the message that will be sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>id</parameter> :</term> - <listitem><simpara>The ID of the chat.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-sent-chat-msg" role="signal"> - <title>The <literal>"sent-chat-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *message, - int id, - gpointer user_data) -</programlisting> - <para> -Emitted after sending a message to a chat. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message was sent on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message that was sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>id</parameter> :</term> - <listitem><simpara>The ID of the chat.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-receiving-chat-msg" role="signal"> - <title>The <literal>"receiving-chat-msg"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleAccount *account, - char **sender, - char **message, - PurpleChatConversation *chat, - int *flags, - gpointer user_data) -</programlisting> - <para> -Emitted when a chat message is received. The callback can replace the name of the sender, the message, or the flags by modifying the pointer to the strings. This can also be used to cancel displaying a message by returning <literal>TRUE</literal>. - </para> - <note><para> -Make sure to free <literal>*sender</literal> and <literal>*message</literal> before you replace them! - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message was received on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>sender</parameter> :</term> - <listitem><simpara>A pointer to the username of the sender.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>A pointer to the message that was sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>A pointer to the chat message flags.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-received-chat-msg" role="signal"> - <title>The <literal>"received-chat-msg"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - char *sender, - char *message, - PurpleChatConversation *chat, - PurpleMessageFlags flags, - gpointer user_data) -</programlisting> - <para> -Emitted after a chat message is received. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the message was received on.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>sender</parameter> :</term> - <listitem><simpara>The username of the sender.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The message that was sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>The chat message flags.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-conversation-created" role="signal"> - <title>The <literal>"conversation-created"</literal> signal</title> -<programlisting> -void user_function (PurpleConversation *conv, - gpointer user_data) -</programlisting> - <para> -Emitted when a new conversation is created. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>conv</parameter> :</term> - <listitem><simpara>The new conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-conversation-updated" role="signal"> - <title>The <literal>"conversation-updated"</literal> signal</title> -<programlisting> -void user_function (PurpleConversation *conv, - PurpleConvUpdateType type, - gpointer user_data) -</programlisting> - <para> -Emitted when a conversation is updated. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>conv</parameter> :</term> - <listitem><simpara>The conversation that was updated.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>type</parameter> :</term> - <listitem><simpara>The type of update that was made.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-deleting-conversation" role="signal"> - <title>The <literal>"deleting-conversation"</literal> signal</title> -<programlisting> -void user_function (PurpleConversation *conv, - gpointer user_data) -</programlisting> - <para> -Emitted just before a conversation is to be destroyed. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>conv</parameter> :</term> - <listitem><simpara>The conversation that's about to be destroyed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-buddy-typing" role="signal"> - <title>The <literal>"buddy-typing"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *name, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy starts typing in a conversation window. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account of the user which is typing.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the user which is typing.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-buddy-typing-stopped" role="signal"> - <title>The <literal>"buddy-typing-stopped"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *name, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy stops typing in a conversation window. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account of the user which stopped typing.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the user which stopped typing.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-user-joining" role="signal"> - <title>The <literal>"chat-user-joining"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleChatConversation *chat, - const char *name, - PurpleChatUserFlags flags, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy is joining a chat, before the list of users in the chat updates to include the new user. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the user that is joining the conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>The flags of the user that is joining the conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>TRUE</literal> if the join should be hidden, or <literal>FALSE</literal> otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-user-joined" role="signal"> - <title>The <literal>"chat-user-joined"</literal> signal</title> -<programlisting> -void user_function (PurpleChatConversation *chat, - const char *name, - PurpleChatUserFlags flags, - gboolean new_arrival, - gpointer user_data) -</programlisting> - <para> -Emitted when a buddy joined a chat, after the users list is updated. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the user that has joined the conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>flags</parameter> :</term> - <listitem><simpara>The flags of the user that has joined the conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>new_arrival</parameter> :</term> - <listitem><simpara>If the buddy is a new arrival.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-join-failed" role="signal"> - <title>The <literal>"chat-join-failed"</literal> signal</title> -<programlisting> -void user_function (PurpleConnection *gc, - GHashTable *components, - gpointer user_data) -</programlisting> - <para> -Emitted when an account fails to join a chat room. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The PurpleConnection of the account which failed to join the chat.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>data</parameter> :</term> - <listitem><simpara>The components passed to purple_serv_join_chat() originally. The hash function should be g_str_hash() and the equal function should be g_str_equal().</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-user-flags" role="signal"> - <title>The <literal>"chat-user-flags"</literal> signal</title> -<programlisting> -void user_function (PurpleChatUser *chatuser, - PurpleChatUserFlags oldflags, - PurpleChatUserFlags newflags, - gpointer user_data) -</programlisting> - <para> -Emitted when a user in a chat changes flags. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chatuser</parameter> :</term> - <listitem><simpara>The chat user whose flags changed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>oldflags</parameter> :</term> - <listitem><simpara>The old flags.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>newflags</parameter> :</term> - <listitem><simpara>The new flags.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-user-leaving" role="signal"> - <title>The <literal>"chat-user-leaving"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleChatConversation *chat, - const char *name, - const char *reason, - gpointer user_data) -</programlisting> - <para> -Emitted when a user is leaving a chat, before the user list is updated. This may include an optional reason why the user is leaving. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the user that is leaving the chat.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>reason</parameter> :</term> - <listitem><simpara>The optional reason why the user is leaving.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>TRUE</literal> if the leave should be hidden, or <literal>FALSE</literal> otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-user-left" role="signal"> - <title>The <literal>"chat-user-left"</literal> signal</title> -<programlisting> -void user_function (PurpleChatConversation *chat, - const char *name, - const char *reason, - gpointer user_data) -</programlisting> - <para> -Emitted when a user leaves a chat, after the user list is updated. This may include an optional reason why the user is leaving. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the user that left the chat.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>reason</parameter> :</term> - <listitem><simpara>The optional reason why the user left the chat.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-inviting-user" role="signal"> - <title>The <literal>"chat-inviting-user"</literal> signal</title> -<programlisting> -void user_function (PurpleChatConversation *chat, - const char *name, - char **invite_message, - gpointer user_data) -</programlisting> - <para> -Emitted when a user is being invited to the chat. The callback can replace the invite message to the invitee by modifying the pointer to the invite message. - </para> - <note><para> -Make sure to free <literal>*invite_message</literal> before you replace it! - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the user being invited.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>invite_message</parameter> :</term> - <listitem><simpara>A pointer to the reason why a user is being invited.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-invited-user" role="signal"> - <title>The <literal>"chat-invited-user"</literal> signal</title> -<programlisting> -void user_function (PurpleChatConversation *conv, - const char *name, - const char *invite_message, - gpointer user_data) -</programlisting> - <para> -Emitted when a user invited another user to a chat. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the user that was invited.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>invite_message</parameter> :</term> - <listitem><simpara>The message to be sent to the user when invited.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-invited" role="signal"> - <title>The <literal>"chat-invited"</literal> signal</title> -<programlisting> -gint user_function (PurpleAccount *account, - const char *inviter, - const char *chat, - const char *invite_messageconst GHashTable *components, - gpointer user_data) -</programlisting> - <para> -Emitted when an account was invited to a chat. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account being invited.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>inviter</parameter> :</term> - <listitem><simpara>The username of the person inviting the account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The name of the chat you're being invited to.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>invite_message</parameter> :</term> - <listitem><simpara>The optional invite message.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>components</parameter> :</term> - <listitem><simpara>The components necessary if you want to call purple_serv_join_chat().</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>Less than zero if the invitation should be rejected, greater than zero if the invitation should be accepted. If zero is returned, the default behavior will be maintained: the user will be prompted.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-invite-blocked" role="signal"> - <title>The <literal>"chat-invite-blocked"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *inviter, - const char *name, - const char *message, - GHashTable *data) -</programlisting> - <para> -Emitted when an invitation to join a chat is blocked. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account the invitation was sent to.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>inviter</parameter> :</term> - <listitem><simpara>The name of the person sending the invitation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>name</parameter> :</term> - <listitem><simpara>The name of the chat invited to.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The invitation message sent.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>data</parameter> :</term> - <listitem><simpara>Hashtable containing data about the invited chat.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-joined" role="signal"> - <title>The <literal>"chat-joined"</literal> signal</title> -<programlisting> -void user_function (PurpleChatConversation *chat, - gpointer user_data) -</programlisting> - <para> -Emitted when an account joins a chat room. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The conversation that joined the chat room.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-left" role="signal"> - <title>The <literal>"chat-left"</literal> signal</title> -<programlisting> -void user_function (PurpleChatConversation *chat, - gpointer user_data) -</programlisting> - <para> -Emitted when an account leaves a chat room. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The conversation that left the chat room.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-chat-topic-changed" role="signal"> - <title>The <literal>"chat-topic-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleChatConversation *chat, - const char *who, - const char *topic, - gpointer user_data) -</programlisting> - <para> -Emitted when the topic is changed in a chat. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>chat</parameter> :</term> - <listitem><simpara>The chat conversation whose topic changed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>who</parameter> :</term> - <listitem><simpara>The name of the person that changed the topic.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>topic</parameter> :</term> - <listitem><simpara>The new topic.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-conversation-extended-menu" role="signal"> - <title>The <literal>"conversation-extended-menu"</literal> signal</title> -<programlisting> -void user_function (PurpleConversation *conv, - GList **list, - gpointer user_data) -</programlisting> - <para> -Emitted when the UI requests a list of plugin actions for a conversation. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>conv</parameter> :</term> - <listitem><simpara>The conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>list</parameter> :</term> - <listitem><simpara>A pointer to the list of actions.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-cleared-message-history" role="signal"> - <title>The <literal>"cleared-message-history"</literal> signal</title> -<programlisting> -void user_function (PurpleConversation *conv, - gpointer user_data) -</programlisting> - <para> -Emitted when the conversation history is cleared. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>conv</parameter> :</term> - <listitem><simpara>The conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-sent-attention" role="signal"> - <title>The <literal>"sent-attention"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *who, - PurpleConversation *conv, - guint type, - gpointer user_data) -</programlisting> - <para> -Emitted when receiving an attention message (buzz, nudge, etc.). - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>who</parameter> :</term> - <listitem><simpara>The name of the person receiving the attention.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>conv</parameter> :</term> - <listitem><simpara>The conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>type</parameter> :</term> - <listitem><simpara>The attention type (an index starting at 0).</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="conversations-got-attention" role="signal"> - <title>The <literal>"got-attention"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *who, - PurpleConversation *conv, - guint type, - gpointer user_data) -</programlisting> - <para> -Emitted when receiving an attention message (buzz, nudge, etc.). - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>who</parameter> :</term> - <listitem><simpara>The name of the person sending the attention.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>conv</parameter> :</term> - <listitem><simpara>The conversation.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>type</parameter> :</term> - <listitem><simpara>The attention type (an index starting at 0).</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_core.md b/doc/reference/libpurple/signals_core.md new file mode 100644 index 0000000000..ae7396d687 --- /dev/null +++ b/doc/reference/libpurple/signals_core.md @@ -0,0 +1,51 @@ +Title: Core Signals +Slug: core-signals + +## Core Signals + +### Signal List + +* [core-quitting](#quitting) +* [core-uri-handler](#uri-handler) + +### Signal Details + +#### quitting + +```c +void user_function(gpointer user_data); +``` + +Emitted when libpurple is quitting. + +**Parameters:** + +**user_data** +: User data set when the signal handler was connected. + +---- + +#### uri-handler + +```c +gboolean user_function(const gchar *proto, + const gchar *cmd, + GHashTable *params, + gpointer user_data); +``` + +Emitted when handling a registered URI. + +**Parameters:** + +**proto** +: The protocol of the URI. + +**cmd** +: The 'command' of the URI. + +**params** +: Any key/value parameters from the URI. + +**user_data** +: User data set when the signal handler was connected. diff --git a/doc/reference/libpurple/signals_core.xml b/doc/reference/libpurple/signals_core.xml deleted file mode 100644 index 777fd1ad17..0000000000 --- a/doc/reference/libpurple/signals_core.xml +++ /dev/null @@ -1,68 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-core"> -<title>Core signals</title> - -<refsect1 id="core.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="core-quitting">quitting</link>" - "<link linkend="core-uri-handler">uri-handler</link>" -</synopsis> -</refsect1> - -<refsect1 id="core.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="core-quitting" role="signal"> - <title>The <literal>"quitting"</literal> signal</title> -<programlisting> -void user_function (gpointer user_data) -</programlisting> - <para> -Emitted when libpurple is quitting. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="core-uri-handler" role="signal"> - <title>The <literal>"uri-handler"</literal> signal</title> -<programlisting> -gboolean user_function (const gchar *proto, - const gchar *cmd, - GHashTable *params, - gpointer user_data) -</programlisting> - <para> -Emitted when handling a registered URI. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>proto</parameter> :</term> - <listitem><simpara>The protocol of the URI.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>cmd</parameter> :</term> - <listitem><simpara>The 'command' of the URI.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>params</parameter> :</term> - <listitem><simpara>Any key/value parameters from the URI.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_imgstore.xml b/doc/reference/libpurple/signals_imgstore.xml deleted file mode 100644 index debcfb854f..0000000000 --- a/doc/reference/libpurple/signals_imgstore.xml +++ /dev/null @@ -1,44 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-imgstore"> -<title>Stored Image signals</title> - -<refsect1 id="imgstores.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="imgstores-image-deleting">image-deleting</link>" -</synopsis> -</refsect1> - -<refsect1 id="imgstores.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="imgstores-image-deleting" role="signal"> - <title>The <literal>"image-deleting"</literal> signal</title> -<programlisting> -char * user_function (const PurpleStoredImage *img, - gpointer user_data) -</programlisting> - <para> -Emitted when a #PurpleStoredImage is about to be destroyed. This allows for what amounts to weak references. Code can hold onto a pointer to the PurpleStoredImage without actually "holding" a reference. They can then use a signal handler to let them know when their img is about to be destroyed. - </para> - <note><para> -It's not possible to purple_imgstore_ref() img to save it. - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>img</parameter> :</term> - <listitem><simpara>The image about to be destroyed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_jabber.md b/doc/reference/libpurple/signals_jabber.md new file mode 100644 index 0000000000..cea3058d79 --- /dev/null +++ b/doc/reference/libpurple/signals_jabber.md @@ -0,0 +1,277 @@ +Title: Jabber Signals +Slug: jabber-signals + +## Jabber Signals + +### Signal List + +* [jabber-receiving-iq](#jabber-receiving-iq) +* [jabber-receiving-message](#jabber-receiving-message) +* [jabber-receiving-presence](#jabber-receiving-presence) +* [jabber-watched-iq](#jabber-watched-iq) +* [jabber-register-namespace-watcher](#jabber-register-namespace-watcher) +* [jabber-unregister-namespace-watcher](#jabber-unregister-namespace-watcher) +* [jabber-sending-xmlnode](#jabber-sending-xmlnode) +* [jabber-receiving-xmlnode](#jabber-receiving-xmlnode) + +### Signal Details + +#### jabber-receiving-iq + +```c +gboolean user_function(PurpleConnection *gc, + const gchar *type, + const gchar *id, + const gchar *from, + PurpleXmlNode *iq, + gpointer user_data); +``` + +Emitted when an XMPP IQ stanza is received. Allows a plugin to process IQ +stanzas. + +**Parameters:** + +**gc** +: The connection on which the stanza is received. + +**type** +: The IQ type ('get', 'set', 'result', or 'error'). + +**id** +: The ID attribute from the stanza. MUST NOT be NULL. + +**from** +: The originator of the stanza. MAY BE NULL if the stanza originated from the +user's server. + +**iq** +: The full stanza received. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the plugin processed this stanza and *nobody else* should process it. +`FALSE` otherwise. + +---- + +#### jabber-receiving-message + +```c +gboolean user_function(PurpleConnection *gc, + const gchar *type, + const gchar *id, + const gchar *from, + const gchar *to, + PurpleXmlNode *message, + gpointer user_data); +``` + +Emitted when an XMPP message stanza is received. Allows a plugin to process +message stanzas. + +**Parameters:** + +**gc** +: The connection on which the stanza is received. + +**type** +: The message type (see rfc3921 or rfc3921bis). + +**id** +: The ID attribute from the stanza. MAY BE NULL. + +**from** +: The originator of the stanza. MAY BE NULL if the stanza originated from the +user's server. + +**to** +: The destination of the stanza. This is probably either the full JID of the +receiver or the receiver's bare JID. + +**message** +: The full stanza received. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the plugin processed this stanza and *nobody else* should process it. +`FALSE` otherwise. + +---- + +#### jabber-receiving-presence + +```c +gboolean user_function(PurpleConnection *gc, + const gchar *type, + const gchar *from, + PurpleXmlNode *presence, + gpointer user_data) +``` + +Emitted when an XMPP presence stanza is received. Allows a plugin to process +presence stanzas. + +**Parameters:** + +**gc** +: The connection on which the stanza is received. + +**type** +: The presence type (see rfc3921 or rfc3921bis). NULL indicates this is an +"available" (i.e. online) presence. + +**from** +: The originator of the stanza. MAY BE NULL if the stanza originated from the +user's server. + +**presence** +: The full stanza received. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the plugin processed this stanza and *nobody else* should process it. +`FALSE` otherwise. + +---- + +#### jabber-watched-iq + +```c +gboolean user_function(PurpleConnection *gc, + const gchar *type, + const gchar *id, + const gchar *from, + PurpleXmlNode *child, + gpointer user_data); +``` + +Emitted when an IQ with a watched (child, namespace) pair is received. See jabber-register-namespace-watcher and jabber-unregister-namespace-watcher. + +**Parameters:** + +**gc** +: The connection on which the stanza is received. + +**type** +: The IQ type ('get', 'set', 'result', or 'error'). + +**id** +: The ID attribute from the stanza. MUST NOT be NULL. + +**from** +: The originator of the stanza. MAY BE NULL if the stanza originated from the user's server. + +**child** +: The child node with namespace. + +**user_data** +: user data set when the signal handler was connected. + +**Returns:** + +`TRUE` if the plugin processed this stanza and *nobody else* should process it. +`FALSE` otherwise. + +---- + +#### jabber-register-namespace-watcher + +```c +void user_function(const gchar *node, + const gchar *namespace, + gpointer user_data) +``` + +Emit this signal to register your desire to have specific IQ stanzas to be +emitted via the jabber-watched-iq signal when received. + +**Parameters:** + +**node** +: The IQ child name to longer watch. + +**namespace** +: The IQ child namespace to longer watch. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### jabber-unregister-namespace-watcher + +```c +void user_function(const gchar *node, + const gchar *namespace, + gpointer user_data); +``` + +Emit this signal to unregister your desire to have specific IQ stanzas to be +emitted via the jabber-watched-iq signal when received. + +**Parameters:** + +**node** +: The IQ child name to no longer watch. + +**namespace** +: The IQ child namespace to no longer watch. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### jabber-sending-xmlnode + +```c +void user_function(PurpleConnection *gc, + PurpleXmlNode **stanza, + gpointer user_data); +``` + +Emit this signal (`purple_signal_emit`) to send a stanza. It is preferred to use this instead of purple_protocol_server_iface_send_raw. + +**Parameters:** + +**gc** +: The connection on which to send the stanza. + +**stanza** +: The stanza to send. If stanza is not NULL after being sent, the emitter should free it. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### jabber-receiving-xmlnode + +```c +void user_function(PurpleConnection *gc, + PurpleXmlNode **stanza, + gpointer user_data); +``` + +Emitted when an XMPP stanza is received. Allows a plugin to process any stanza. + +**Parameters:** + +**gc** +: The connection on which the stanza was received. + +**stanza** +: The received stanza. Set stanza to NULL (and free it) to stop processing the stanza. + +**user_data** +: user data set when the signal handler was connected. diff --git a/doc/reference/libpurple/signals_jabber.xml b/doc/reference/libpurple/signals_jabber.xml deleted file mode 100644 index 413efd929f..0000000000 --- a/doc/reference/libpurple/signals_jabber.xml +++ /dev/null @@ -1,311 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-jabber"> -<title>Jabber signals</title> - -<refsect1 id="jabber.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="jabber-jabber-receiving-iq">jabber-receiving-iq</link>" - "<link linkend="jabber-jabber-receiving-message">jabber-receiving-message</link>" - "<link linkend="jabber-jabber-receiving-presence">jabber-receiving-presence</link>" - "<link linkend="jabber-jabber-watched-iq">jabber-watched-iq</link>" - "<link linkend="jabber-jabber-register-namespace-watcher">jabber-register-namespace-watcher</link>" - "<link linkend="jabber-jabber-unregister-namespace-watcher">jabber-unregister-namespace-watcher</link>" - "<link linkend="jabber-jabber-sending-xmlnode">jabber-sending-xmlnode</link>" - "<link linkend="jabber-jabber-receiving-xmlnode">jabber-receiving-xmlnode</link>" -</synopsis> -</refsect1> - -<refsect1 id="jabber.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="jabber-jabber-receiving-iq" role="signal"> - <title>The <literal>"jabber-receiving-iq"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleConnection *gc, - const char *type, - const char *id, - const char *from, - PurpleXmlNode *iq, - gpointer user_data) -</programlisting> - <para> -Emitted when an XMPP IQ stanza is received. Allows a plugin to process IQ stanzas. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection on which the stanza is received.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>type</parameter> :</term> - <listitem><simpara>The IQ type ('get', 'set', 'result', or 'error').</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>id</parameter> :</term> - <listitem><simpara>The ID attribute from the stanza. MUST NOT be NULL.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>from</parameter> :</term> - <listitem><simpara>The originator of the stanza. MAY BE NULL if the stanza originated from the user's server.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>iq</parameter> :</term> - <listitem><simpara>The full stanza received.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>TRUE if the plugin processed this stanza and *nobody else* should process it. FALSE otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="jabber-jabber-receiving-message" role="signal"> - <title>The <literal>"jabber-receiving-message"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleConnection *gc, - const char *type, - const char *id, - const char *from, - const char *to, - PurpleXmlNode *message, - gpointer user_data) -</programlisting> - <para> -Emitted when an XMPP message stanza is received. Allows a plugin to process message stanzas. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection on which the stanza is received.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>type</parameter> :</term> - <listitem><simpara>The message type (see rfc3921 or rfc3921bis).</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>id</parameter> :</term> - <listitem><simpara>The ID attribute from the stanza. MAY BE NULL.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>from</parameter> :</term> - <listitem><simpara>The originator of the stanza. MAY BE NULL if the stanza originated from the user's server.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>to</parameter> :</term> - <listitem><simpara>The destination of the stanza. This is probably either the full JID of the receiver or the receiver's bare JID.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>message</parameter> :</term> - <listitem><simpara>The full stanza received.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>TRUE if the plugin processed this stanza and *nobody else* should process it. FALSE otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="jabber-jabber-receiving-presence" role="signal"> - <title>The <literal>"jabber-receiving-presence"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleConnection *gc, - const char *type, - const char *from, - PurpleXmlNode *presence, - gpointer user_data) -</programlisting> - <para> -Emitted when an XMPP presence stanza is received. Allows a plugin to process presence stanzas. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection on which the stanza is received.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>type</parameter> :</term> - <listitem><simpara>The presence type (see rfc3921 or rfc3921bis). NULL indicates this is an "available" (i.e. online) presence.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>from</parameter> :</term> - <listitem><simpara>The originator of the stanza. MAY BE NULL if the stanza originated from the user's server.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>presence</parameter> :</term> - <listitem><simpara>The full stanza received.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>TRUE if the plugin processed this stanza and *nobody else* should process it. FALSE otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="jabber-jabber-watched-iq" role="signal"> - <title>The <literal>"jabber-watched-iq"</literal> signal</title> -<programlisting> -gboolean user_function (PurpleConnection *gc, - const char *type, - const char *id, - const char *from, - PurpleXmlNode *child, - gpointer user_data) -</programlisting> - <para> -Emitted when an IQ with a watched (child, namespace) pair is received. See jabber-register-namespace-watcher and jabber-unregister-namespace-watcher. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection on which the stanza is received.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>type</parameter> :</term> - <listitem><simpara>The IQ type ('get', 'set', 'result', or 'error').</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>id</parameter> :</term> - <listitem><simpara>The ID attribute from the stanza. MUST NOT be NULL.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>from</parameter> :</term> - <listitem><simpara>The originator of the stanza. MAY BE NULL if the stanza originated from the user's server.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>child</parameter> :</term> - <listitem><simpara>The child node with namespace.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>TRUE if the plugin processed this stanza and *nobody else* should process it. FALSE otherwise.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="jabber-jabber-register-namespace-watcher" role="signal"> - <title>The <literal>"jabber-register-namespace-watcher"</literal> signal</title> -<programlisting> -void user_function (const char *node, - const char *namespace, - gpointer user_data) -</programlisting> - <para> -Emit this signal to register your desire to have specific IQ stanzas to be emitted via the jabber-watched-iq signal when received. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>node</parameter> :</term> - <listitem><simpara>The IQ child name to longer watch.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>namespace</parameter> :</term> - <listitem><simpara>The IQ child namespace to longer watch.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="jabber-jabber-unregister-namespace-watcher" role="signal"> - <title>The <literal>"jabber-unregister-namespace-watcher"</literal> signal</title> -<programlisting> -void user_function (const char *node, - const char *namespace, - gpointer user_data) -</programlisting> - <para> -Emit this signal to unregister your desire to have specific IQ stanzas to be emitted via the jabber-watched-iq signal when received. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>node</parameter> :</term> - <listitem><simpara>The IQ child name to no longer watch.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>namespace</parameter> :</term> - <listitem><simpara>The IQ child namespace to no longer watch.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="jabber-jabber-sending-xmlnode" role="signal"> - <title>The <literal>"jabber-sending-xmlnode"</literal> signal</title> -<programlisting> -void user_function (PurpleConnection *gc, - PurpleXmlNode **stanza, - gpointer user_data) -</programlisting> - <para> -Emit this signal (<literal>purple_signal_emit</literal>) to send a stanza. It is preferred to use this instead of purple_protocol_server_iface_send_raw. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection on which to send the stanza.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>stanza</parameter> :</term> - <listitem><simpara>The stanza to send. If stanza is not NULL after being sent, the emitter should free it.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="jabber-jabber-receiving-xmlnode" role="signal"> - <title>The <literal>"jabber-receiving-xmlnode"</literal> signal</title> -<programlisting> -void user_function (PurpleConnection *gc, - PurpleXmlNode **stanza, - gpointer user_data) -</programlisting> - <para> -Emitted when an XMPP stanza is received. Allows a plugin to process any stanza. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>gc</parameter> :</term> - <listitem><simpara>The connection on which the stanza was received.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>stanza</parameter> :</term> - <listitem><simpara>The received stanza. Set stanza to NULL (and free it) to stop processing the stanza.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_log.xml b/doc/reference/libpurple/signals_log.xml deleted file mode 100644 index 9a7f1e9062..0000000000 --- a/doc/reference/libpurple/signals_log.xml +++ /dev/null @@ -1,58 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-log"> -<title>Log signals</title> - -<refsect1 id="logs.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="logs-log-timestamp">log-timestamp</link>" -</synopsis> -</refsect1> - -<refsect1 id="logs.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="logs-log-timestamp" role="signal"> - <title>The <literal>"log-timestamp"</literal> signal</title> -<programlisting> -char * user_function (PurpleLog *log, - time_t when, - gboolean show_date, - gpointer user_data) -</programlisting> - <para> -Emitted to allow plugins to customize the timestamp on a message being logged. - </para> - <note><para> -Plugins must be careful of logs with a type of PURPLE_LOG_SYSTEM. - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>log</parameter> :</term> - <listitem><simpara>The log the message belongs to.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>when</parameter> :</term> - <listitem><simpara>The time to be converted to a string.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>show_date</parameter> :</term> - <listitem><simpara>Whether the date should be displayed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>A textual representation of the time, or <literal>NULL</literal> to use a default format.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_notify.md b/doc/reference/libpurple/signals_notify.md new file mode 100644 index 0000000000..3fcff8fc48 --- /dev/null +++ b/doc/reference/libpurple/signals_notify.md @@ -0,0 +1,106 @@ +Title: Notify Signals +Slug: notify-signals + +## Notify Signals + +### Signal List + +* [displaying-userinfo](#displaying-userinfo) +* [displaying-email-notification](#displaying-email-notification) +* [displaying-emails-notification](#displaying-emails-notification) + +### Signal Details + +#### displaying-userinfo + +```c +void user_function(PurpleAccount *account, + const gchar *who, + PurpleNotifyUserInfo *user_info, + gpointer user_data); +``` + +Emitted before userinfo is handed to the UI to display. `user_info` can be manipulated via the PurpleNotifyUserInfo API in notify.c. + +> If adding a PurpleNotifyUserInfoEntry, be sure not to free it -- +> PurpleNotifyUserInfo assumes responsibility for its objects. + +**Parameters:** + +**account** +: The account on which the info was obtained. + +**who** +: The name of the buddy whose info is to be displayed. + +**user_info** +: The information to be displayed, as PurpleNotifyUserInfoEntry objects. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### displaying-email-notification + +```c +void user_function(const gchar *subject, + const gchar *from, + const gchar *to, + const gchar *url, + gpointer user_data); +``` + +Emitted before notification of a single email is handed to the UI to display. + +**Parameters:** + +**subject** +: Subject of email being notified of. + +**from** +: Who the email is from. + +**to** +: Who the email is to. + +**url** +: A url to view the email. + +**user_data** +: user data set when the signal handler was connected. + +---- + +#### displaying-emails-notification + +```c +void user_function(const gchar **subjects, + const gchar **froms, + const gchar **tos, + const gchar **urls, + guint count, + gpointer user_data) +``` + +Emitted before notification of multiple emails is handed to the UI to display. + +**Parameters:** + +**subjects** +: Subjects of emails being notified of. + +**froms** +: Who the emails are from. + +**tos** +: Who the emails are to. + +**urls** +: The urls to view the emails. + +**count** +: Number of emails being notified of. + +**user_data** +: user data set when the signal handler was connected. diff --git a/doc/reference/libpurple/signals_notify.xml b/doc/reference/libpurple/signals_notify.xml deleted file mode 100644 index 26f9f65978..0000000000 --- a/doc/reference/libpurple/signals_notify.xml +++ /dev/null @@ -1,133 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-notify"> -<title>Notify signals</title> - -<refsect1 id="notify.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="notify-displaying-userinfo">displaying-userinfo</link>" - "<link linkend="notify-displaying-email-notification">displaying-email-notification</link>" - "<link linkend="notify-displaying-emails-notification">displaying-emails-notification</link>" -</synopsis> -</refsect1> - -<refsect1 id="notify.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="notify-displaying-userinfo" role="signal"> - <title>The <literal>"displaying-userinfo"</literal> signal</title> -<programlisting> -void user_function (PurpleAccount *account, - const char *who, - PurpleNotifyUserInfo *user_info, - gpointer user_data) -</programlisting> - <para> -Emitted before userinfo is handed to the UI to display. <literal>user_info</literal> can be manipulated via the PurpleNotifyUserInfo API in notify.c. - </para> - <note><para> -If adding a PurpleNotifyUserInfoEntry, be sure not to free it -- PurpleNotifyUserInfo assumes responsibility for its objects. - </para></note> - <variablelist role="params"> - <varlistentry> - <term><parameter>account</parameter> :</term> - <listitem><simpara>The account on which the info was obtained.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>who</parameter> :</term> - <listitem><simpara>The name of the buddy whose info is to be displayed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_info</parameter> :</term> - <listitem><simpara>The information to be displayed, as PurpleNotifyUserInfoEntry objects.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="notify-displaying-email-notification" role="signal"> - <title>The <literal>"displaying-email-notification"</literal> signal</title> -<programlisting> -void user_function (const char *subject, - const char *from, - const char *to, - const char *url, - gpointer user_data) -</programlisting> - <para> -Emitted before notification of a single email is handed to the UI to display. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>subject</parameter> :</term> - <listitem><simpara>Subject of email being notified of.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>from</parameter> :</term> - <listitem><simpara>Who the email is from.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>to</parameter> :</term> - <listitem><simpara>Who the email is to.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>url</parameter> :</term> - <listitem><simpara>A url to view the email.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="notify-displaying-emails-notification" role="signal"> - <title>The <literal>"displaying-emails-notification"</literal> signal</title> -<programlisting> -void user_function (const char **subjects, - const char **froms, - const char **tos, - const char **urls, - guint count, - gpointer user_data) -</programlisting> - <para> -Emitted before notification of multiple emails is handed to the UI to display. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>subjects</parameter> :</term> - <listitem><simpara>Subjects of emails being notified of.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>froms</parameter> :</term> - <listitem><simpara>Who the emails are from.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>tos</parameter> :</term> - <listitem><simpara>Who the emails are to.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>urls</parameter> :</term> - <listitem><simpara>The urls to view the emails.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>count</parameter> :</term> - <listitem><simpara>Number of emails being notified of.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_plugin.xml b/doc/reference/libpurple/signals_plugin.xml deleted file mode 100644 index d5fe3cb90b..0000000000 --- a/doc/reference/libpurple/signals_plugin.xml +++ /dev/null @@ -1,63 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-plugin"> -<title>Plugin signals</title> - -<refsect1 id="plugins.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="plugins-plugin-load">plugin-load</link>" - "<link linkend="plugins-plugin-unload">plugin-unload</link>" -</synopsis> -</refsect1> - -<refsect1 id="plugins.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="plugins-plugin-load" role="signal"> - <title>The <literal>"plugin-load"</literal> signal</title> -<programlisting> -void user_function (PurplePlugin *plugin, - gpointer user_data) -</programlisting> - <para> -Emitted when a plugin is loaded. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>plugin</parameter> :</term> - <listitem><simpara>The plugin that was loaded.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -<refsect2 id="plugins-plugin-unload" role="signal"> - <title>The <literal>"plugin-unload"</literal> signal</title> -<programlisting> -void user_function (PurplePlugin *plugin, - gpointer user_data) -</programlisting> - <para> -Emitted when a plugin is unloaded. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>plugin</parameter> :</term> - <listitem><simpara>The plugin that was unloaded.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>user_data</parameter> :</term> - <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_savedstatus.md b/doc/reference/libpurple/signals_savedstatus.md new file mode 100644 index 0000000000..f962195a04 --- /dev/null +++ b/doc/reference/libpurple/signals_savedstatus.md @@ -0,0 +1,20 @@ +Title: Saved Status Signals +Slug: saved-status-signals + +## Saved Status Signals + +### Signal List + +* [savedstatus-changed](#savedstatus-changed) + +### Signal Details + +#### savedstatus-changed + +```c +void user_function(PurpleSavedStatus *new, + PurpleSavedStatus *old, + gpointer user_data); +``` + +Emitted when a new saved status is activated. diff --git a/doc/reference/libpurple/signals_savedstatus.xml b/doc/reference/libpurple/signals_savedstatus.xml deleted file mode 100644 index abc0e12f63..0000000000 --- a/doc/reference/libpurple/signals_savedstatus.xml +++ /dev/null @@ -1,32 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-savedstatus"> -<title>Saved Status signals</title> - -<refsect1 id="savedstatuses.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="savedstatuses-savedstatus-changed">savedstatus-changed</link>" -</synopsis> -</refsect1> - -<refsect1 id="savedstatuses.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="savedstatuses-savedstatus-changed" role="signal"> - <title>The <literal>"savedstatus-changed"</literal> signal</title> -<programlisting> -void user_function (PurpleSavedStatus *new, - PurpleSavedStatus *old, - gpointer user_data) -</programlisting> - <para> -Emitted when a new saved status is activated. - </para> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/signals_xfer.md b/doc/reference/libpurple/signals_xfer.md new file mode 100644 index 0000000000..670bbb6a06 --- /dev/null +++ b/doc/reference/libpurple/signals_xfer.md @@ -0,0 +1,26 @@ +Title: File Transfer Signals +Slug: file-transfer-signals + +## File Transfer Signals + +### Signal List + +* [file-recv-request](#file-recv-request) + +### Signal Detail + +#### file-recv-request + +```c +void user_function(PurpleXfer *xfer, gpointer data); +``` + +Emitted before the user is prompted for an incoming file-transfer. Plugins can intercept the signal to auto-accept/auto-reject the requests. To auto-accept the file transfer, use purple_xfer_request_accepted(). To auto-reject, set the status of the xfer to PURPLE_XFER_STATUS_CANCEL_LOCAL. + +**Parameters:** + +**xfer** +: The file transfer. + +**data** +: User data. diff --git a/doc/reference/libpurple/signals_xfer.xml b/doc/reference/libpurple/signals_xfer.xml deleted file mode 100644 index 1e29389746..0000000000 --- a/doc/reference/libpurple/signals_xfer.xml +++ /dev/null @@ -1,41 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-signals-xfer"> -<title>File Transfer signals</title> - -<refsect1 id="xfers.signals" role="signal_proto"> -<title role="signal_proto.title">List of signals</title> -<synopsis> - "<link linkend="xfers-file-recv-request">file-recv-request</link>" -</synopsis> -</refsect1> - -<refsect1 id="xfers.signal-details" role="signals"> -<title role="signals.title">Signal details</title> - -<refsect2 id="xfers-file-recv-request" role="signal"> - <title>The <literal>"file-recv-request"</literal> signal</title> -<programlisting> -void user_function (PurpleXfer *xfer, - gpointer data) -</programlisting> - <para> -Emitted before the user is prompted for an incoming file-transfer. Plugins can intercept the signal to auto-accept/auto-reject the requests. To auto-accept the file transfer, use purple_xfer_request_accepted(). To auto-reject, set the status of the xfer to PURPLE_XFER_STATUS_CANCEL_LOCAL. - </para> - <variablelist role="params"> - <varlistentry> - <term><parameter>xfer</parameter> :</term> - <listitem><simpara>The file transfer.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>data</parameter> :</term> - <listitem><simpara>User data.</simpara></listitem> - </varlistentry> - </variablelist> -</refsect2> - -</refsect1> - -</chapter> diff --git a/doc/reference/libpurple/tut_c_plugins.md b/doc/reference/libpurple/tut_c_plugins.md new file mode 100644 index 0000000000..a9fda1142e --- /dev/null +++ b/doc/reference/libpurple/tut_c_plugins.md @@ -0,0 +1,101 @@ +Title: C Plugin Tutorial +Slug: c-plugin-tutorial + +## C Plugin Tutorial + +### Introduction + +C plugins are native plugins. They have complete access to all of the API, +and can do basically whatever they want. All of the protocol plugins are +also written in C. + +### Getting Started + +To develop a plugin you need to have the libpurple and (for UI plugins) the +Pidgin/Finch source code or development headers. It is generally a good idea +to compile against the same version of Pidgin that you are running. You may +also want to develop against the code in our Mercurial repository if you need +to use a new feature. Please do not abuse our Mercurial repository, however. + +### An Example + +I know every tutorial has a hello world, so why should libpurple be any +different? + +```c +#include <purple.h> + +static GPluginPluginInfo * +hello_world_query(GError **error) +{ + const gchar * const authors[] = { + "Author Name <e@mail>", + NULL + }; + + /* For specific notes on the meanings of each of these members, consult the + C Plugin Howto on the website. */ + return purple_plugin_info_new ( + "name", "Hello World!", + "version", VERSION, + "category", "Example", + "summary", "Hello World Plugin", + "description", "Hello World Plugin", + "authors", authors, + "website", "http://helloworld.tld", + "abi-version", PURPLE_ABI_VERSION, + NULL + ); +} + +static gboolean +hello_world_load(GPluginPlugin *plugin, GError **error) +{ + purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!", + "This is the Hello World! plugin :)", + NULL, NULL, NULL, NULL); + + return TRUE; +} + +static gboolean +hello_world_unload(GPluginPlugin *plugin, GError **error) +{ + return TRUE; +} + +GPLUGIN_NATIVE_PLUGIN_DECLARE(hello_world) +``` + +Okay, so what does all this mean? We start off by including purple.h. This +file includes all the libpurple header files. + +`hello_world_query`, `hello_world_load` and `hello_world_unload` are functions +that must be implemented in every plugin. These functions are named according +to the value passed to `GPLUGIN_NATIVE_PLUGIN_DECLARE` which is described +below. + +`hello_world_query` is called when the plugin is queried by the plugin system, +and returns various information about the plugin in form of a newly created +instance of `GPluginPluginInfo` or a subclass. For a list of all available +properties, see `purple_plugin_info_new()`. + +If anything should go wrong during the query you can return an error by using +`g_set_error()` on the `error` argument. + +`hello_world_load` is called when the plugin is loaded. That is the user has +enabled the plugin or libpurple is loading a plugin that was previously loaded. +You can initialize any variables, register dynamic types, and so on in this +function. Plugins may also want to add their preferences to the pref +tree--more about that later. In this plugin we'll just use it to display a +message. Just like `hello_world_query` if there are any errors that arise, you +can call `g_set_error()` on the `error` agument and return `FALSE`. + +`hello_world_unload` is called when the plugin is unloaded. That is, when the +user has manually unloaded the plugin or the program is shutting down. We can +use it to wrap up everything, and free our variables. Again, if there are any +errors, you can call `g_set_error()` on the `error` argument and return `FALSE`. + +Finally we have `GPLUGIN_NATIVE_PLUGIN_DECLARE()`. It is a helper macro that +makes creating plugins easier. It has a single argument which is the prefix +used for the `_query`, `_load`, and `_unload` functions. diff --git a/doc/reference/libpurple/tut_c_plugins.xml b/doc/reference/libpurple/tut_c_plugins.xml deleted file mode 100644 index 7756f18536..0000000000 --- a/doc/reference/libpurple/tut_c_plugins.xml +++ /dev/null @@ -1,137 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-tut-c-plugins"> - <title>C Plugins tutorial</title> - - <sect2 id="tut-c-plugins-introduction"> - <title>Introduction</title> - <para> - C plugins are native plugins. They have complete access to all of the API, - and can do basically whatever they want. All of the protocol plugins are - also written in C. - </para> - </sect2> - - <sect2 id="tut-c-plugins-getting-started"> - <title>Getting Started</title> - <para> - To develop a plugin you need to have the libpurple and (for UI plugins) the - Pidgin/Finch source code or development headers. It is generally a good idea - to compile against the same version of Pidgin that you are running. You may - also want to develop against the code in our Mercurial repository if you need - to use a new feature. Please do not abuse our Mercurial repository, however. - </para> - </sect2> - - <sect2 id="tut-c-plugins-hello-world"> - <title>An Example</title> - <para> - I know every tutorial has a hello world, so why should libpurple be any - different? - -<example> -<title>Hello World!</title> -<programlisting> -#include <purple.h> - -static GPluginPluginInfo * -hello_world_query(GError **error) -{ - const gchar * const authors[] = { - "Author Name <e@mail>", - NULL - }; - - /* For specific notes on the meanings of each of these members, consult the - C Plugin Howto on the website. */ - return purple_plugin_info_new ( - "name", "Hello World!", - "version", VERSION, - "category", "Example", - "summary", "Hello World Plugin", - "description", "Hello World Plugin", - "authors", authors, - "website", "http://helloworld.tld", - "abi-version", PURPLE_ABI_VERSION, - NULL - ); -} - -static gboolean -hello_world_load(GPluginPlugin *plugin, GError **error) -{ - purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!", - "This is the Hello World! plugin :)", - NULL, NULL, NULL, NULL); - - return TRUE; -} - -static gboolean -hello_world_unload(GPluginPlugin *plugin, GError **error) -{ - return TRUE; -} - -GPLUGIN_NATIVE_PLUGIN_DECLARE(hello_world) -</programlisting> -</example> - </para> - - <para> - Okay, so what does all this mean? We start off by including purple.h. This - file includes all the libpurple header files. - </para> - - <para> - <literal>hello_world_query</literal>, <literal>hello_world_load</literal> and - <literal>hello_world_unload</literal> are functions that must be implemented - in every plugin. These functions are named according to the value passed - to <literal>GPLUGIN_NATIVE_PLUGIN_DECLARE</literal> which is described below. - </para> - - <para> - <literal>hello_world_query</literal> is called when the plugin is queried by - the plugin system, and returns various information about the plugin in form - of a newly created instance of <literal>GPluginPluginInfo</literal> or a - subclass. For a list of all available properties, see - <link linkend="purple-plugin-info-new"><function>purple_plugin_info_new()</function></link>. - </para> - - <para> - If anything should go wrong during the query you can return an error by using - <function>g_set_error()</function> on the <literal>error</literal> argument. - </para> - - <para> - <literal>hello_world_load</literal> is called when the plugin is loaded. That - is the user has enabled the plugin or libpurple is loading a plugin that was - previously loaded. You can initialize any variables, register dynamic types, - and so on in this function. Plugins may also want to add their preferences - to the pref tree--more about that later. In this plugin we'll just use it to - display a message. Just like - <literal>hello_world_query</literal> if there are any errors that arise, you - can call <function>g_set_error()</function> on the <literal>error</literal> - agument and return <literal>FALSE</literal>. - </para> - - <para> - <literal>hello_world_unload</literal> is called when the plugin is unloaded. - That is, when the user has manually unloaded the plugin or the program is - shutting down. We can use it to wrap up everything, and free our variables. - Again, if there are any errors, you can call - <function>g_set_error()</function> on the <literal>error</literal> argument - and return <literal>FALSE</literal>. - </para> - - <para> - Finally we have - <link linkend="GPLUGIN_NATIVE_PLUGIN_DECLARE:CAPS"><function>GPLUGIN_NATIVE_PLUGIN_DECLARE()</function></link>. - It is a helper macro that makes creating plugins easier. It has a single - argument which is the prefix used for the <literal>_query</literal>, - <literal>_load</literal>, and <literal>_unload</literal> functions. - </para> - </sect2> -</chapter> diff --git a/doc/reference/libpurple/tut_signals.xml b/doc/reference/libpurple/tut_signals.xml deleted file mode 100644 index 77ccbfe1ec..0000000000 --- a/doc/reference/libpurple/tut_signals.xml +++ /dev/null @@ -1,203 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-tut-signals"> - <title>Signals tutorial</title> - - <sect2 id="tut-signals-introduction"> - <title>Introduction</title> - <para> - The libpurple signals interface is used for general event notification, such - as plugins being loaded or unloaded, allowing the GUI frontend to respond - appropriately to changing internal data. Unfortunately, its use is not at all - obvious from the information in the header files. This document uses code - snippets from the Pidgin/libpurple plugin systems to illustrate the proper - use of signals. - </para> - </sect2> - - <sect2 id="tut-signals-overview"> - <title>Overview of Purple-signals</title> - <para> - Signals in libpurple are very similar to those in GTK+. When certain events - happen, a named signal is "emitted" from a certain object. Emitting the - signal triggers a series of callbacks that have been "connected" to that - signal for that object. These callbacks take appropriate action in response - to the signal. - </para> - </sect2> - - <sect2 id="tut-signals-registering"> - <title>Registering a Signal</title> - <para> - The first step of using a signal is registering it with libpurple so that - callbacks may be connected to it. This is done using - <link linkend="purple-signal-register"><function>purple_signal_register()</function></link>. - Here is a slightly modified example from - <link linkend="purple-plugins-init"><function>purple_plugins_init()</function></link> - in <literal>plugins.c</literal>: - -<programlisting> -purple_signal_register(purple_plugins_get_handle(), /* Instance */ - "plugin-load", /* Signal name */ - purple_marshal_VOID__POINTER,/* Marshal function */ - G_TYPE_NONE, /* Callback return type */ - 1, /* Number of callback arguments (not including void *data) */ - PURPLE_TYPE_PLUGIN /* Type of first callback argument */ -); -</programlisting> - </para> - - <sect3> - <title>Instance</title> - <para> - A reference to the object from which this signal is emitted, and to which - potential callbacks should be connected. In this case, it will be the entire - plugin module emitting the signal. - </para> - </sect3> - - <sect3> - <title>Signal Name</title> - <para> - Unique identifier for the signal itself. - </para> - </sect3> - - <sect3> - <title>Callback function definition</title> - <para> - The rest of the arguments specify the form of the callback function. - - <itemizedlist> - <listitem><para><emphasis>Marshal function</emphasis></para><para> - <literal>purple_marshal_VOID__POINTER</literal> represents the callback - function prototype, not including a "data" argument, explained later. The form - is <literal>purple_marshal_RETURNVALUETYPE__ARG1TYPE_ARG2TYPE_ETC</literal>. - See <link linkend="libpurple-signals">signals.h</link> for more possible types. - </para> - - <para> - In this case, the callback will have the form -<programlisting> -void cb(void *arg1, void *data) -</programlisting> - </para> - - <para> - If <literal>purple_marshal_BOOLEAN__POINTER_POINTER_POINTER</literal> were - specified, it would be: -<programlisting> -gboolean cb(void *arg1, void *arg2, void *arg3, void *data) -</programlisting> - - The <literal>void *data</literal> argument at the end of each callback function - provides the data argument given to - <link linkend="purple-signal-connect"><function>purple_signal_connect()</function></link>. - </para></listitem> - - <listitem><para><emphasis>Callback return type</emphasis></para><para> - In our case, this is G_TYPE_NONE, meaning "returns void". -<!-- TODO This could be described better. --> - </para></listitem> - - <listitem><para><emphasis>Number of callback arguments</emphasis></para><para> - The number of arguments (not including <literal>data</literal>) that the callback function - will take. - </para></listitem> - - <listitem><para><emphasis>Type of argument</emphasis></para><para> - <literal>PURPLE_TYPE_PLUGIN</literal> specifies that the first argument given to the callback - will be a <literal>PurplePlugin*</literal>. You will need as many "type of argument" - arguments to - <link linkend="purple-signal-register"><function>purple_signal_register()</function></link> - as you specified in - "Number of arguments" above. - -<!-- TODO Describe this more. --> - </para></listitem> - </itemizedlist> - </para> - </sect3> - </sect2> - - <sect2 id="tut-signals-connect"> - <title>Connecting to the signal</title> - <para> - Once the signal is registered, you can connect callbacks to it. First, you - must define a callback function, such as this one from gtkplugin.c : -<programlisting> -static void plugin_load_cb(PurplePlugin *plugin, gpointer data) -{ - GtkTreeView *view = (GtkTreeView *)data; - plugin_loading_common(plugin, view, TRUE); -} -</programlisting> - Note that the callback function prototype matches that specified in the call - to <link linkend="purple-signal-register"><function>purple_signal_register()</function></link> - above. - </para> - - <para> - Once the callback function is defined, you can connect it to the signal. - Again from gtkplugin.c , in <function>pidgin_plugin_dialog_show()</function>: -<programlisting> -purple_signal_connect(purple_plugins_get_handle(), "plugin-load", /* What to connect to */ - plugin_dialog, /* Object receiving the signal */ - PURPLE_CALLBACK(plugin_load_cb), /* Callback function */ - event_view, /* Data to pass to the callback function -); -</programlisting> - </para> - - <para> - The first two arguments ("What to connect to") specify the object emitting - the signal (the plugin module) and what signal to listen for ("plugin-load"). - </para> - - <para> - The object receiving the signal is <literal>plugin_dialog</literal> , the Pidgin plugins - dialog. When <literal>plugin_dialog</literal> is deleted, then - <literal>purple_signals_disconnect_by_handle(plugin_dialog)</literal> should be called to - remove all signal connections it is associated with. - </para> - - <para> - The callback function is given using a helper macro, and finally the - <literal>data</literal> argument to be passed to - <literal>plugin_load_cb</literal> is given as <literal>event_view</literal>, - a pointer to the GTK widget that <literal>plugin_load_cb</literal> needs to update. - </para> - </sect2> - - <sect2 id="tut-signals-emit-signal"> - <title>Emitting a signal</title> - <para> - Connecting callbacks to signals is all well and good, but how do you "fire" - the signal and trigger the callback? At some point, you must "emit" the - signal, which immediately calls all connected callbacks. - </para> - - <para> - As seen in <link linkend="purple-plugin-load"><function>purple_plugin_load()</function></link> - in plugin.c: -<programlisting> -purple_signal_emit(purple_plugins_get_handle(), "plugin-load", plugin); -</programlisting> - This causes the signal "plugin-load" to be emitted from the plugin module - (given by - <link linkend="purple-plugins-get-handle"><function>purple_plugins_get_handle()</function></link>), - with the newly loaded plugin as - the argument to pass to any registered callback functions. - </para> - - <para> - In our example, <literal>plugin_load_cb</literal> is called immediately as -<programlisting> -plugin_load_cb(plugin, event_view); -</programlisting> - and does whatever it does. - </para> - </sect2> -</chapter> diff --git a/doc/reference/libpurple/ui_ops.xml b/doc/reference/libpurple/ui_ops.xml deleted file mode 100644 index 70a20dab7f..0000000000 --- a/doc/reference/libpurple/ui_ops.xml +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version='1.0' encoding="ISO-8859-1"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ -]> -<chapter id="chapter-ui-ops"> - <title>List of <literal>UiOps</literal> Structures</title> - - <para> - When implementing a UI for libpurple, you need to fill in various UiOps - structures: - - <itemizedlist> -<listitem><link linkend="PurpleAccountUiOps"><literal>PurpleAccountUiOps</literal></link></listitem> -<listitem><link linkend="PurpleCommandsUiOps"><literal>PurpleCommandsUiOps</literal></link></listitem> -<listitem><link linkend="PurpleConnectionUiOps"><literal>PurpleConnectionUiOps</literal></link></listitem> -<listitem><link linkend="PurpleConversationUiOps"><literal>PurpleConversationUiOps</literal></link></listitem> -<listitem><link linkend="PurpleCoreUiOps"><literal>PurpleCoreUiOps</literal></link></listitem> -<listitem><link linkend="PurpleIdleUiOps"><literal>PurpleIdleUiOps</literal></link></listitem> -<listitem><link linkend="PurpleNotifyUiOps"><literal>PurpleNotifyUiOps</literal></link></listitem> -<listitem><link linkend="PurpleRequestUiOps"><literal>PurpleRequestUiOps</literal></link></listitem> -<listitem><link linkend="PurpleRoomlistUiOps"><literal>PurpleRoomlistUiOps</literal></link></listitem> -<listitem><link linkend="PurpleWhiteboardUiOps"><literal>PurpleWhiteboardUiOps</literal></link></listitem> -<listitem><link linkend="PurpleXferUiOps"><literal>PurpleXferUiOps</literal></link></listitem> - </itemizedlist> - </para> - -</chapter> diff --git a/doc/reference/libpurple/urlmap.js b/doc/reference/libpurple/urlmap.js new file mode 100644 index 0000000000..28b131fd48 --- /dev/null +++ b/doc/reference/libpurple/urlmap.js @@ -0,0 +1,9 @@ +// SPDX-FileCopyrightText: 2021 GNOME Foundation +// SPDX-License-Identifier: LGPL-2.1-or-later + +// A map between namespaces and base URLs for their online documentation +baseURLs = [ + [ 'GLib', 'https://docs.gtk.org/glib/' ], + [ 'GObject', 'https://docs.gtk.org/gobject/' ], + [ 'GPlugin', 'https://docs.imfreedom.org/gplugin/' ], +] diff --git a/doc/reference/libpurple/version.xml.in b/doc/reference/libpurple/version.xml.in deleted file mode 100644 index 405528f9af..0000000000 --- a/doc/reference/libpurple/version.xml.in +++ /dev/null @@ -1 +0,0 @@ -@PURPLE_VERSION@ |