aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorfriendica <info@friendica.com>2013-11-28 18:46:59 -0800
committerfriendica <info@friendica.com>2013-11-28 18:46:59 -0800
commit94c293f2c6c8ff7d7a1a0f45ab9ab2ecfaa16372 (patch)
tree50b10043a2099da49b27eb58f67bcdc8d0d603ea
parenteae33275840495d27717f95f9647cf96c1c1d6cd (diff)
downloadvolse-hubzilla-94c293f2c6c8ff7d7a1a0f45ab9ab2ecfaa16372.tar.gz
volse-hubzilla-94c293f2c6c8ff7d7a1a0f45ab9ab2ecfaa16372.tar.bz2
volse-hubzilla-94c293f2c6c8ff7d7a1a0f45ab9ab2ecfaa16372.zip
doco
-rw-r--r--include/zot.php27
1 files changed, 21 insertions, 6 deletions
diff --git a/include/zot.php b/include/zot.php
index 725dc58e3..9777f7ae4 100644
--- a/include/zot.php
+++ b/include/zot.php
@@ -79,8 +79,8 @@ function zot_get_hublocs($hash) {
* zot it to the other side
*
* @param array $channel => sender channel structure
- * @param string $type => one of 'ping', 'pickup', 'purge', 'refresh', 'notify', 'auth_check'
- * @param array $recipients => envelope information, array of string $xchan_hash; empty for public posts
+ * @param string $type => packet type: one of 'ping', 'pickup', 'purge', 'refresh', 'notify', 'auth_check'
+ * @param array $recipients => envelope information, array ( 'guid' => string, 'guid_sig' => string ); empty for public posts
* @param string $remote_key => optional public site key of target hub used to encrypt entire packet
* NOTE: remote_key and encrypted packets are required for 'auth_check' packets, optional for all others
* @param string $secret => random string, required for packets which require verification/callback
@@ -228,12 +228,27 @@ function zot_finger($webbie,$channel,$autofallback = true) {
}
/**
- * @function: zot_refresh
+ * @function: zot_refresh($them, $channel = null)
*
- * zot_refresh is typically invoked when somebody has changed permissions of a channel and they are notified
- * to fetch new permissions via a finger operation. This may result in a new connection (abook entry) being added to a local channel
- * and it may result in auto-permissions being granted.
+ * zot_refresh is typically invoked when somebody has changed permissions of a channel and they are notified
+ * to fetch new permissions via a finger/discovery operation. This may result in a new connection
+ * (abook entry) being added to a local channel and it may result in auto-permissions being granted.
+ *
+ * Friending in zot is accomplished by sending a refresh packet to a specific channel which indicates a
+ * permission change has been made by the sender which affects the target channel. The hub controlling
+ * the target channel does targetted discovery (a zot-finger request requesting permissions for the local
+ * channel). These are decoded here, and if necessary and abook structure (addressbook) is created to store
+ * the permissions assigned to this channel.
+ *
+ * Initially these abook structures are created with a 'pending' flag, so that no reverse permissions are
+ * implied until this is approved by the owner channel. A channel can also auto-populate permissions in
+ * return and send back a refresh packet of its own. This is used by forum and group communication channels
+ * so that friending and membership in the channel's "club" is automatic.
+ *
+ * @param array $them => xchan structure of sender
+ * @param array $channel => local channel structure of target recipient, required for "friending" operations
*
+ * @returns boolean true if successful, else false
*/
function zot_refresh($them,$channel = null) {