# HG changeset patch # User Myhailo Danylenko # Date 1345477985 -10800 # Node ID 0477d4800fbd1a8358997f9aeb97cc0798e9270a # Parent f23b9521b4d6edb0962434c9f0ebb8ae89f4c142 Rearrange docs diff -r f23b9521b4d6 -r 0477d4800fbd CMakeLists.txt --- a/CMakeLists.txt Wed Aug 08 14:43:55 2012 +0300 +++ b/CMakeLists.txt Mon Aug 20 18:53:05 2012 +0300 @@ -1,7 +1,7 @@ -## Copyright 2009 Myhailo Danylenko -# This file is part of mcabber module writing howto examples. +## Copyright 2009-2012 Myhailo Danylenko +# This file is part of mcabber-pep # -# Examples are free software: you can redistribute it and/or modify +# mcabber-pep is a free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 2 of the License, or # (at your option) any later version. @@ -118,8 +118,8 @@ ## Installation install(TARGETS ${MODULE_LIST} DESTINATION lib/mcabber) -install(FILES ${PROJECT_BINARY_DIR}/pep.rc COPYING TODO README DESTINATION share/doc/${CPACK_PACKAGE_NAME}) -install(DIRECTORY doc/ DESTINATION share/doc/${CPACK_PACKAGE_NAME} PATTERN "*~" EXCLUDE) +install(FILES ${PROJECT_BINARY_DIR}/pep.rc COPYING docs/todo.mdwn docs/readme.mdwn DESTINATION share/doc/${CPACK_PACKAGE_NAME}) +install(DIRECTORY docs/ DESTINATION share/doc/${CPACK_PACKAGE_NAME} PATTERN "*~" EXCLUDE) install(FILES pep.h ${PROJECT_BINARY_DIR}/pep_mood.h ${PROJECT_BINARY_DIR}/pep_tune.h diff -r f23b9521b4d6 -r 0477d4800fbd README --- a/README Wed Aug 08 14:43:55 2012 +0300 +++ b/README Mon Aug 20 18:53:05 2012 +0300 @@ -1,74 +1,1 @@ - -# Personal Eventing Protocol modules - -This is a set of modules, that provide notfication about other's events -and allow you to publish yours. - -Pep module provides common listener for incoming PEP events. - -Tune module provides '/tune' command to publish music, you are listening -to at the moment. However, it does not by itself does that. You'll need -some other module, that will provide music information, like 'mpd' one. -Alternatively, you can set up some scripts to publish information with -'/tune' command via fifo. - -Mood module provides '/mood' command to publish your current mood. -Currently it does not check for validity of its input, so, it's strongly -suggested to use provided completion for first argument. - -Geoloc module provides '/geoloc' command to publish your current location. -Currently, there are no known use cases of this module, but I hope, that -someday there will be a module, that will retrieve geolocation information -from devices and use this module to publish it. - -Activity module provides '/activity' command to publish your current activity. -Currently it does not check for validity of its input either, so, please -use completion for first two arguments. - -Note: In order for you to actually publish something, your server must -support PEP, and that is still not that widely available. Still, even -if your server does not, you can load modules to be notified about your -buddies events. - -All of the modules also provide C headers for other C modules to use -to publish data. Note, however, that I plan to switch to events interface -for that - it provides multiplexing ability, and in general is more -flexible. - -# Installation - -To install it, you need: -cmake -make -gcc -glib -loudmouth -mcabber's headers - -Then do -$ mkdir build -$ cd build -$ cmake .. -$ make edit_cache -$ make -# make install - -Debian users can instead of make install do -$ fakeroot make package -# dpkg -i libmcabber-pep*.deb - -Users of other distributions can select appropriate package -generator, using cache editor. - -# License - -This code underlies terms of GNU GPL v2 or later. You can find it in file COPYING -from this distribution or on a GNU web-site . - -# Contacts - -I will be happy to get feedback, patches, suggestions, etc. -You can send me email or contact via jabber . - - -- Myhailo Danylenko - +docs/readme.mdwn \ No newline at end of file diff -r f23b9521b4d6 -r 0477d4800fbd TODO --- a/TODO Wed Aug 08 14:43:55 2012 +0300 +++ b/TODO Mon Aug 20 18:53:05 2012 +0300 @@ -1,15 +1,1 @@ - -* due to server bugs, some offline buddies are still notified on publication, - causing error reply, that pep accepts as event. check message type/presence of error tag. -* check input/output for validity, where applicable -* extract common code into one place -* add avatar - * pep_avatar, avatar_cache, avatar, aavatar (separate) - * hook_avatar_metadata_in @ pep_avatar - | hook_avatar_need_data_in (or symbol-resolved request) @ avatar_cache - V hook_avatar_data_in @ pep_avatar - hook_avatar_in @ avatar_cache - * (!!!) how to handle outgoing event? what and where should do what? - * handle url avatars (curl) - * report absence of avatar - +docs/todo.mdwn \ No newline at end of file diff -r f23b9521b4d6 -r 0477d4800fbd doc/activities.txt --- a/doc/activities.txt Wed Aug 08 14:43:55 2012 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,78 +0,0 @@ - * doing_chores - + buying_groceries - + cleaning - + cooking - + doing_maintenance - + doing_the_dishes - + doing_the_laundry - + gardening - + running_an_errand - + walking_the_dog - * drinking - + having_a_beer - + having_coffee - + having_tea - * eating - + having_a_snack - + having_breakfast - + having_dinner - + having_lunch - * exercising - + cycling - + dancing - + hiking - + jogging - + playing_sports - + running - + skiing - + swimming - + working_out - * grooming - + at_the_spa - + brushing_teeth - + getting_a_haircut - + shaving - + taking_a_bath - + taking_a_shower - * having_appointment - * inactive - + day_off - + hanging_out - + hiding - + on_vacation - + praying - + scheduled_holiday - + sleeping - + thinking - * relaxing - + fishing - + gaming - + going_out - + partying - + reading - + rehearsing - + shopping - + smoking - + socializing - + sunbathing - + watching_tv - + watching_a_movie - * talking - + in_real_life - + on_the_phone - + on_video_phone - * traveling - + commuting - + cycling - + driving - + in_a_car - + on_a_bus - + on_a_plane - + on_a_train - + on_a_trip - + walking - * working - + coding - + in_a_meeting - + studying - + writing diff -r f23b9521b4d6 -r 0477d4800fbd doc/api.mdwn --- a/doc/api.mdwn Wed Aug 08 14:43:55 2012 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,103 +0,0 @@ - -# Events interface - -Events are currently designed for useage with pep notifications, but -potentially could be used with any notification system, eg a module, that adds -currently playing song to your status. - -Every module pair (eg pep_tune and tune) use a pair of hooks. One for incoming -notifications ('*-in') and one for the cases, when server needs to be notified -about user state change ('*-out'). Note, that '*-out' causes server -notification, not vice versa. In general, these hooks have the same set of fields, -except that incoming events also have 'from' field, that is mandatory. - -For more clear description of fields and what can be put in there, refer to -corresponding XEPs. - -* [XEP-0118](http://xmpp.org/extensions/xep-0118.html) - tune -* [XEP-0107](http://xmpp.org/extensions/xep-0107.html) - mood -* [XEP-0108](http://xmpp.org/extensions/xep-0108.html) - activity -* [XEP-0080](http://xmpp.org/extensions/xep-0080.html) - geoloc - -## tune-* -* argtist -* length -* rating -* source -* title -* track -* uri -* state (stop, pause, play) - -## mood-* -* mood -* text - -## activity-* -* major -* minor -* text - -## geoloc-* -* accuracy -* alt -* area -* bearing -* building -* country -* datum -* description -* error -* floor -* lat -* locality -* lon -* postalcode -* region -* room -* speed -* street -* text -* timestamp -* uri - -# C interface - -## general conventions - -### NS_* -XMLNS namespace constants. - -### HOOK_* -Hook name constants. Usually are the same as actual hook name, but -uppercased, with 'HOOK_' added and with underscores instead of dashes. - -### OPT_* -MCabber option names. Should not be enclosed in braces. - -### pep_*_request ( to, error ) -Request corresponding data from the jid, specified in 'to'. -'error' may be used for error control. If no error occured, -and remote side have replied with notification stanza, call -to one of this functions will eventually result in corresponding -event '*-in'. Currently there's no way to detect an -error on the remote side (eg, if it does not support PEP). - -## pep - -### (*pep_xmlns_handler_t) ( from, node, n, id, userdata ) -Type of function to supply as a handler for pep xmlns namespace. -'from' is a jid. -'node' is pep node. -'n' is loudmouth message node object, containing xmlns-specific data. -'userdata' is pointer to data, passed at registration time. - -### pep_register_xmlns_handler ( xmlns, handler, userdata, notify ) -Specify a handler for xmlns namespace. -'userdata' will be directly specified. -'notify' is a function, that may be called for userdata destruction. - -### pep_unregister_xmlns_handler ( xmlns ) -Remove handler from given xmlns namespace. - - diff -r f23b9521b4d6 -r 0477d4800fbd doc/avv_api.mdwn --- a/doc/avv_api.mdwn Wed Aug 08 14:43:55 2012 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,17 +0,0 @@ - -# Api versions: - -mood:1 provide mood_publish() -pep_mood:1 mood:1 + provide mood_request(), use events -pep_mood:2 drop mood_publish, rename to pep_mood_request(), header name change -tune:1 provide tune_publish() -pep_tune:1 tune:1 + provide tune_request(), use events -pep_tune:2 drop tune_publish, rename to pep_tune_request(), header name change -geoloc:1 provide geoloc_publish() -pep_geoloc:1 geoloc:1 + provide geoloc_request(), use events -pep_geoloc:2 drop geoloc_publish, rename to pep_geoloc_request(), header name change -activity:1 provide activity_publish() -pep_activity:1 activity:1 + provide activity_request(), use events -pep_activity:2 drop activity_publish, rename to pep_activity_request(), header name change - - diff -r f23b9521b4d6 -r 0477d4800fbd doc/moods.txt --- a/doc/moods.txt Wed Aug 08 14:43:55 2012 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,84 +0,0 @@ -afraid -amazed -amorous -angry -annoyed -anxious -aroused -ashamed -bored -brave -calm -cautious -cold -confident -confused -contemplative -contented -cranky -crazy -creative -curious -dejected -depressed -disappointed -disgusted -dismayed -distracted -embarrassed -envious -excited -flirtatious -frustrated -grateful -grieving -grumpy -guilty -happy -hopeful -hot -humbled -humiliated -hungry -hurt -impressed -in_awe -in_love -indignant -interested -intoxicated -invincible -jealous -lonely -lost -lucky -mean -moody -nervous -neutral -offended -outraged -playful -proud -relaxed -relieved -remorseful -restless -sad -sarcastic -satisfied -serious -shocked -shy -sick -sleepy -spontaneous -stressed -strong -surprised -thankful -thirsty -tired -undefined -weak -worried diff -r f23b9521b4d6 -r 0477d4800fbd docs/activities.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/activities.mdwn Mon Aug 20 18:53:05 2012 +0300 @@ -0,0 +1,81 @@ +Activities as per XEP-108: + + * doing_chores + + buying_groceries + + cleaning + + cooking + + doing_maintenance + + doing_the_dishes + + doing_the_laundry + + gardening + + running_an_errand + + walking_the_dog + * drinking + + having_a_beer + + having_coffee + + having_tea + * eating + + having_a_snack + + having_breakfast + + having_dinner + + having_lunch + * exercising + + cycling + + dancing + + hiking + + jogging + + playing_sports + + running + + skiing + + swimming + + working_out + * grooming + + at_the_spa + + brushing_teeth + + getting_a_haircut + + shaving + + taking_a_bath + + taking_a_shower + * having_appointment + * inactive + + day_off + + hanging_out + + hiding + + on_vacation + + praying + + scheduled_holiday + + sleeping + + thinking + * relaxing + + fishing + + gaming + + going_out + + partying + + reading + + rehearsing + + shopping + + smoking + + socializing + + sunbathing + + watching_tv + + watching_a_movie + * talking + + in_real_life + + on_the_phone + + on_video_phone + * traveling + + commuting + + cycling + + driving + + in_a_car + + on_a_bus + + on_a_plane + + on_a_train + + on_a_trip + + walking + * working + + coding + + in_a_meeting + + studying + + writing + diff -r f23b9521b4d6 -r 0477d4800fbd docs/api.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api.mdwn Mon Aug 20 18:53:05 2012 +0300 @@ -0,0 +1,103 @@ + +# Events interface + +Events are currently designed for useage with pep notifications, but +potentially could be used with any notification system, eg a module, that adds +currently playing song to your status. + +Every module pair (eg pep_tune and tune) use a pair of hooks. One for incoming +notifications ('*-in') and one for the cases, when server needs to be notified +about user state change ('*-out'). Note, that '*-out' causes server +notification, not vice versa. In general, these hooks have the same set of fields, +except that incoming events also have 'from' field, that is mandatory. + +For more clear description of fields and what can be put in there, refer to +corresponding XEPs. + +* [XEP-0118](http://xmpp.org/extensions/xep-0118.html) - tune +* [XEP-0107](http://xmpp.org/extensions/xep-0107.html) - mood +* [XEP-0108](http://xmpp.org/extensions/xep-0108.html) - activity +* [XEP-0080](http://xmpp.org/extensions/xep-0080.html) - geoloc + +## tune-* +* argtist +* length +* rating +* source +* title +* track +* uri +* state (stop, pause, play) + +## mood-* +* mood +* text + +## activity-* +* major +* minor +* text + +## geoloc-* +* accuracy +* alt +* area +* bearing +* building +* country +* datum +* description +* error +* floor +* lat +* locality +* lon +* postalcode +* region +* room +* speed +* street +* text +* timestamp +* uri + +# C interface + +## general conventions + +### NS_* +XMLNS namespace constants. + +### HOOK_* +Hook name constants. Usually are the same as actual hook name, but +uppercased, with 'HOOK_' added and with underscores instead of dashes. + +### OPT_* +MCabber option names. Should not be enclosed in braces. + +### pep_*_request ( to, error ) +Request corresponding data from the jid, specified in 'to'. +'error' may be used for error control. If no error occured, +and remote side have replied with notification stanza, call +to one of this functions will eventually result in corresponding +event '*-in'. Currently there's no way to detect an +error on the remote side (eg, if it does not support PEP). + +## pep + +### (*pep_xmlns_handler_t) ( from, node, n, id, userdata ) +Type of function to supply as a handler for pep xmlns namespace. +'from' is a jid. +'node' is pep node. +'n' is loudmouth message node object, containing xmlns-specific data. +'userdata' is pointer to data, passed at registration time. + +### pep_register_xmlns_handler ( xmlns, handler, userdata, notify ) +Specify a handler for xmlns namespace. +'userdata' will be directly specified. +'notify' is a function, that may be called for userdata destruction. + +### pep_unregister_xmlns_handler ( xmlns ) +Remove handler from given xmlns namespace. + + diff -r f23b9521b4d6 -r 0477d4800fbd docs/avv_api.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/avv_api.mdwn Mon Aug 20 18:53:05 2012 +0300 @@ -0,0 +1,17 @@ + +# Api versions: + +mood:1 provide mood_publish() +pep_mood:1 mood:1 + provide mood_request(), use events +pep_mood:2 drop mood_publish, rename to pep_mood_request(), header name change +tune:1 provide tune_publish() +pep_tune:1 tune:1 + provide tune_request(), use events +pep_tune:2 drop tune_publish, rename to pep_tune_request(), header name change +geoloc:1 provide geoloc_publish() +pep_geoloc:1 geoloc:1 + provide geoloc_request(), use events +pep_geoloc:2 drop geoloc_publish, rename to pep_geoloc_request(), header name change +activity:1 provide activity_publish() +pep_activity:1 activity:1 + provide activity_request(), use events +pep_activity:2 drop activity_publish, rename to pep_activity_request(), header name change + + diff -r f23b9521b4d6 -r 0477d4800fbd docs/index.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/index.mdwn Mon Aug 20 18:53:05 2012 +0300 @@ -0,0 +1,9 @@ + +[[!meta title="mcabber-pep"]] + +# Personal Eventing Protocol for MCabber + +Suite of modules to publish and process pep tune, mood, +geoloc and activity events. + +[ [[!hg mcabber-pep desc="SOURCE"]] ] [ [[README|readme]] ] [ [[TODO|todo]] ] [ [[API|api]] ] [ [[AVV API|avv_api]] ] diff -r f23b9521b4d6 -r 0477d4800fbd docs/moods.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/moods.mdwn Mon Aug 20 18:53:05 2012 +0300 @@ -0,0 +1,87 @@ +Moods as per XEP-107: + + * afraid + * amazed + * amorous + * angry + * annoyed + * anxious + * aroused + * ashamed + * bored + * brave + * calm + * cautious + * cold + * confident + * confused + * contemplative + * contented + * cranky + * crazy + * creative + * curious + * dejected + * depressed + * disappointed + * disgusted + * dismayed + * distracted + * embarrassed + * envious + * excited + * flirtatious + * frustrated + * grateful + * grieving + * grumpy + * guilty + * happy + * hopeful + * hot + * humbled + * humiliated + * hungry + * hurt + * impressed + * in_awe + * in_love + * indignant + * interested + * intoxicated + * invincible + * jealous + * lonely + * lost + * lucky + * mean + * moody + * nervous + * neutral + * offended + * outraged + * playful + * proud + * relaxed + * relieved + * remorseful + * restless + * sad + * sarcastic + * satisfied + * serious + * shocked + * shy + * sick + * sleepy + * spontaneous + * stressed + * strong + * surprised + * thankful + * thirsty + * tired + * undefined + * weak + * worried + diff -r f23b9521b4d6 -r 0477d4800fbd docs/readme.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/readme.mdwn Mon Aug 20 18:53:05 2012 +0300 @@ -0,0 +1,85 @@ + +# Personal Eventing Protocol modules + +This is a set of modules, that provide notfication about other's events +and allow you to publish yours. + +'Pep' module provides common listener for incoming PEP events. + +'Tune' module provides '/tune' command to publish music, you are +listening to at the moment. However, it does not by itself does that. +You'll need some other module, that will provide music information, +like 'mpd' one. Alternatively, you can set up some scripts to publish +information with '/tune' command via fifo. + +'Mood' module provides '/mood' command to publish your current mood. +Currently it does not check for validity of its input, so, it's +strongly suggested to use provided completion for first argument. +[[List of valid moods|moods]] + +'Geoloc' module provides '/geoloc' command to publish your current +location. Currently, there are no known use cases of this module, but I +hope, that someday there will be a module, that will retrieve +geolocation information from devices and use this module to publish it. + +'Activity' module provides '/activity' command to publish your current +activity. Currently it does not check for validity of its input either, +so, please use completion for first two arguments. +[[List of valid activities|activities]] + +Modules recognize options 'tune_interval' and 'geoloc_interval' to +limit publication rate and option 'tune_pause_is_stop', that controls +whether tune should publish empty information for paused state. + +Note: In order for you to actually publish something, your server must +support PEP, and that is still not that widely available. Still, even +if your server does not, you can load modules to be notified about your +buddies events. + +All of the modules also provide C headers for other C modules to use +to publish data. Note, however, that I plan to switch to events +interface for that - it provides multiplexing ability, and in general +is more flexible. + +# Installation + +To install it, you need: + + * mcabber headers + * glib + * loudmouth + * cmake + * make + * c compiler (gcc) + * linker (binutils) + +Then do: + + $ mkdir build + $ cd build + $ cmake .. + $ make edit_cache + $ make + # make install + +Debian users can instead of make install do: + + $ make package + # dpkg -i libmcabber-pep_*.deb + +Users of other distributions can select appropriate package generator, +using cache editor. + +# License + +This code underlies terms of GNU GPL v2 or later. You can find it in +file COPYING from this distribution or on a GNU web-site +. + +# Contact + +I will be happy to get feedback, patches, suggestions, etc. +You can send me email or contact via jabber . + + -- Myhailo Danylenko + diff -r f23b9521b4d6 -r 0477d4800fbd docs/todo.mdwn --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/todo.mdwn Mon Aug 20 18:53:05 2012 +0300 @@ -0,0 +1,15 @@ + +* due to server bugs, some offline buddies are still notified on publication, + causing error reply, that pep accepts as event. check message type/presence of error tag. +* check input/output for validity, where applicable +* extract common code into one place +* add avatar + * pep_avatar, avatar_cache, avatar, aavatar (separate) + * hook_avatar_metadata_in @ pep_avatar + | hook_avatar_need_data_in (or symbol-resolved request) @ avatar_cache + V hook_avatar_data_in @ pep_avatar + hook_avatar_in @ avatar_cache + * (!!!) how to handle outgoing event? what and where should do what? + * handle url avatars (curl) + * report absence of avatar +