Description
Build
Install
Usage
Dev. notes
This plugin provides a RESTful API for pidgin / finch.
It should also be able to provide various ways to remote control pidgin / finch. ATM there's an HTML/JS client that uses most of the API's features.
- cmake
- c++ compiler (g++ / clang)
- development stuff (headers / libs) for
- libpurple
- glib
- jsoncpp library
- microhttpd library
mkdir purple-rest-build
cd purple-rest-build
cmake <PURPLE-REST-REPO>/purple-rest-src
make
Copy the file libpurple-rest.so
from the build dir. to ~/.purple/plugins
.
- /plugins/purple-rest/server-port : listen port
- /plugins/purple-rest/url-prefix : URL prefix (stripped from requests) - useful for nginx / apache redirecting (default value is empty string).
Things to be added to ~/.purple/pref.xml
<pref version='1' name='/'>
<pref name='plugins'>
<pref name='core'>
...
<pref name='purple-rest'>
<pref name='server-port' type='int' value='8888'/>
<pref name='url-prefix' type='string' value=''/>
</pref>
...
Considering the default apache configuration, the web client's files (index.html, purple-rest.js, etc.) should be in:
/var/www/html/purple-rest
- for debian/srv/www/htdocs/purple-rest
- for openSuse
Assuming the HTTP URL is http:https://<WEBSERVER>/purple-rest/
:
- enable proxy module (symlink the files proxy.load, proxy.conf and proxy_http.load)
- add these to default.conf or default-ssl.conf:
<Location "/purple-rest/rest">
ProxyPass http:https://localhost:8888
ProxyPassReverse http:https://localhost:8888
</Location>
- install the yast2-http-server module.
- go to yast -> Network services -> HTTP server -> Server modules
- enable
proxy
andproxy_http
- add these to default-server.conf:
<Location "/purple-rest/rest">
ProxyPass http:https://localhost:8888
ProxyPassReverse http:https://localhost:8888
</Location>
my messages : IM messages (except for system messages in IM conversations) and messages from chat conversations that contain user's nick.
FORMAT : html | json
-
.../v1/FORMAT/messages
- all messages received since the plugin has started -
.../v1/FORMAT/messages/all/start_from/MSG_ID
- messages starting with MSG_ID -
.../v1/FORMAT/conv-messages/ID
- messages for the specified conversation -
.../v1/FORMAT/conv-messages/ID/start_from/MSG_ID
- messages for the specified conversation starting with MSG_ID -
.../v1/FORMAT/conversations/all
- conversations list -
.../v1/FORMAT/accounts/all
- accounts list -
.../v1/FORMAT/accounts/ACC_NAME/status
- get the active status for account; it can be "Active", "Offline", "Unknown" or another status reported by libpurple. -
ACC_NAME can be all - in this case get the active status for all the accounts
-
.../v1/FORMAT/accounts/ACC_NAME/statuses
- get all statuses for account -
ACC_NAME can be all - in this case get the statuses of all the accounts
-
.../v1/FORMAT/my-messages/
- all my messages -
.../v1/FORMAT/my-messages/start_from/MSG_ID
- my messages starting with MSG_ID -
.../v1/FORMAT/buddies/all
- list of all buddies -
.../v1/FORMAT/buddies/online
- list of online buddies -
response for json format
[
{ "group" : "Buddies",
"name" : "purple-rest3@localhost",
"status" : "offline"
},
...
]
-
.../v1/json/status/max_msg_id
- latest message id (json only) -
.../v1/json/status/max_my_msg_id
- latest my message id received (json only) -
.../v1/FORMAT/cmd/clear_history
- clear history
.../v1/FORMAT/conv-messages/ID
- send a message for conversation ID
.../v1/FORMAT/conversations/BUDDY_NAME
- create a new conversation with BUDDY_NAME- for json format the server returns details of the newly created conversation
[
{
"id" : 2,
"name" : "purple-rest@localhost"
}
]
-
.../v1/FORMAT/reset-idle
- reset idle time by calling libpurple'spurple_idle_touch
function (similar to typing something in pidgin / finch window). -
.../v1/FORMAT/accounts/ACC_NAME/status/STATUS
- set active status for the specified account; it can be "Available", "Away", "Invisible" or "Offline". (WIP) -
ACC_NAME can be all
.../v1/FORMAT/conversations/ID
- delete the conversation ID
See dev-notes.md