MDL-65743 lib: update moodle library docs
[moodle.git] / lib / jabber / XMPP / Roster.php
1 <?php
3 namespace BirknerAlex\XMPPHP;
5 /**
6  * XMPPHP: The PHP XMPP Library
7  * Copyright (C) 2008  Nathanael C. Fritz
8  * This file is part of SleekXMPP.
9  *
10  * XMPPHP is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version.
14  *
15  * XMPPHP is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with XMPPHP; if not, write to the Free Software
22  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
23  *
24  * @category   xmpphp
25  * @package    XMPPHP
26  * @author     Nathanael C. Fritz <JID: fritzy@netflint.net>
27  * @author     Stephan Wentz <JID: stephan@jabber.wentz.it>
28  * @author     Michael Garvin <JID: gar@netflint.net>
29  * @author     Alexander Birkner (https://github.com/BirknerAlex)
30  * @copyright  2008 Nathanael C. Fritz
31  */
33 /**
34  * XMPPHP Main Class
35  *
36  * @category   xmpphp
37  * @package    XMPPHP
38  * @author     Nathanael C. Fritz <JID: fritzy@netflint.net>
39  * @author     Stephan Wentz <JID: stephan@jabber.wentz.it>
40  * @author     Michael Garvin <JID: gar@netflint.net>
41  * @copyright  2008 Nathanael C. Fritz
42  * @version    $Id$
43  */
44 class Roster {
45         /**
46          * Roster array, handles contacts and presence.  Indexed by jid.
47          * Contains array with potentially two indexes 'contact' and 'presence'
48          * @var array
49          */
50         protected $roster_array = array();
51         /**
52          * Constructor
53          * 
54          */
55         public function __construct($roster_array = array()) {
56                 if ($this->verifyRoster($roster_array)) {
57                         $this->roster_array = $roster_array; //Allow for prepopulation with existing roster
58                 } else {
59                         $this->roster_array = array();
60                 }
61         }
63         /**
64          *
65          * Check that a given roster array is of a valid structure (empty is still valid)
66          *
67          * @param array $roster_array
68          */
69         protected function verifyRoster($roster_array) {
70                 #TODO once we know *what* a valid roster array looks like
71                 return True;
72         }
74         /**
75          *
76          * Add given contact to roster
77          *
78          * @param string $jid
79          * @param string $subscription
80          * @param string $name
81          * @param array $groups
82          */
83         public function addContact($jid, $subscription, $name='', $groups=array()) {
84                 $contact = array('jid' => $jid, 'subscription' => $subscription, 'name' => $name, 'groups' => $groups);
85                 if ($this->isContact($jid)) {
86                         $this->roster_array[$jid]['contact'] = $contact;
87                 } else {
88                         $this->roster_array[$jid] = array('contact' => $contact);
89                 }
90         }
92         /**
93          * 
94          * Retrieve contact via jid
95          *
96          * @param string $jid
97          */
98         public function getContact($jid) {
99                 if ($this->isContact($jid)) {
100                         return $this->roster_array[$jid]['contact'];
101                 }
102         }
104         /**
105          *
106          * Discover if a contact exists in the roster via jid
107          *
108          * @param string $jid
109          */
110         public function isContact($jid) {
111                 return (array_key_exists($jid, $this->roster_array));
112         }
114         /**
115          *
116          * Set presence
117          *
118          * @param string $presence
119          * @param integer $priority
120          * @param string $show
121          * @param string $status
122         */
123         public function setPresence($presence, $priority, $show, $status) {
124                 $presence = explode('/', $presence, 2);
125                 $jid = $presence[0];
126                 $resource = isset($presence[1]) ? $presence[1] : '';
127                 if ($show != 'unavailable') {
128                         if (!$this->isContact($jid)) {
129                                 $this->addContact($jid, 'not-in-roster');
130                         }
131                         $this->roster_array[$jid]['presence'][$resource] = array('priority' => $priority, 'show' => $show, 'status' => $status);
132                 } else { //Nuke unavailable resources to save memory
133                         unset($this->roster_array[$jid]['resource'][$resource]);
134                         unset($this->roster_array[$jid]['presence'][$resource]);
135                 }
136         }
138         /*
139          *
140          * Return best presence for jid
141          *
142          * @param string $jid
143          */
144         public function getPresence($jid) {
145                 $split = explode('/', $jid, 2);
146                 $jid = $split[0];
147                 if($this->isContact($jid)) {
148                         $current = array('resource' => '', 'active' => '', 'priority' => -129, 'show' => '', 'status' => ''); //Priorities can only be -128 = 127
149                         foreach($this->roster_array[$jid]['presence'] as $resource => $presence) {
150                                 //Highest available priority or just highest priority
151                                 if ($presence['priority'] > $current['priority'] and (($presence['show'] == "chat" or $presence['show'] == "available") or ($current['show'] != "chat" or $current['show'] != "available"))) {
152                                         $current = $presence;
153                                         $current['resource'] = $resource;
154                                 }
155                         }
156                         return $current;
157                 }
158         }
159         /**
160          *
161          * Get roster
162          *
163          */
164         public function getRoster() {
165                 return $this->roster_array;
166         }
168 ?>