diff options
Diffstat (limited to 'include/zot.php')
| -rw-r--r-- | include/zot.php | 27 |
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) { |