3 * StatusNet, the distributed open-source microblogging tool
5 * Superclass for plugins that do instant messaging
9 * LICENCE: This program is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Affero General Public License as published by
11 * the Free Software Foundation, either version 3 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Affero General Public License for more details.
19 * You should have received a copy of the GNU Affero General Public License
20 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 * @author Craig Andrews <candrews@integralblue.com>
25 * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
26 * @link http://status.net/
29 if (!defined('STATUSNET') && !defined('LACONICA')) {
34 * Superclass for plugins that do authentication
36 * Implementations will likely want to override onStartIoManagerClasses() so that their
41 * @author Craig Andrews <candrews@integralblue.com>
42 * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
43 * @link http://status.net/
46 abstract class ImPlugin extends Plugin
48 //name of this IM transport
49 public $transport = null;
50 //list of screennames that should get all public notices
51 public $public = array();
54 * normalize a screenname for comparison
56 * @param string $screenname screenname to normalize
58 * @return string an equivalent screenname in normalized form
60 abstract function normalize($screenname);
64 * validate (ensure the validity of) a screenname
66 * @param string $screenname screenname to validate
70 abstract function validate($screenname);
73 * get the internationalized/translated display name of this IM service
77 abstract function getDisplayName();
80 * send a single notice to a given screenname
81 * The implementation should put raw data, ready to send, into the outgoing
82 * queue using enqueue_outgoing_raw()
84 * @param string $screenname screenname to send to
85 * @param Notice $notice notice to send
87 * @return boolean success value
89 function send_notice($screenname, $notice)
91 return $this->send_message($screenname, $this->format_notice($notice));
95 * send a message (text) to a given screenname
96 * The implementation should put raw data, ready to send, into the outgoing
97 * queue using enqueue_outgoing_raw()
99 * @param string $screenname screenname to send to
100 * @param Notice $body text to send
102 * @return boolean success value
104 abstract function send_message($screenname, $body);
107 * receive a raw message
108 * Raw IM data is taken from the incoming queue, and passed to this function.
109 * It should parse the raw message and call handle_incoming()
111 * Returning false may CAUSE REPROCESSING OF THE QUEUE ITEM, and should
112 * be used for temporary failures only. For permanent failures such as
113 * unrecognized addresses, return true to indicate your processing has
116 * @param object $data raw IM data
118 * @return boolean true if processing completed, false for temporary failures
120 abstract function receive_raw_message($data);
123 * get the screenname of the daemon that sends and receives message for this service
125 * @return string screenname of this plugin
127 abstract function daemon_screenname();
130 * get the microid uri of a given screenname
132 * @param string $screenname screenname
134 * @return string microid uri
136 function microiduri($screenname)
138 return $this->transport . ':' . $screenname;
140 //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - MISC ========================\
143 * Put raw message data (ready to send) into the outgoing queue
145 * @param object $data
147 function enqueue_outgoing_raw($data)
149 $qm = QueueManager::get();
150 $qm->enqueue($data, $this->transport . '-out');
154 * Put raw message data (received, ready to be processed) into the incoming queue
156 * @param object $data
158 function enqueue_incoming_raw($data)
160 $qm = QueueManager::get();
161 $qm->enqueue($data, $this->transport . '-in');
165 * given a screenname, get the corresponding user
167 * @param string $screenname
171 function get_user($screenname)
173 $user_im_prefs = $this->get_user_im_prefs_from_screenname($screenname);
175 $user = User::staticGet('id', $user_im_prefs->user_id);
176 $user_im_prefs->free();
185 * given a screenname, get the User_im_prefs object for this transport
187 * @param string $screenname
189 * @return User_im_prefs user_im_prefs
191 function get_user_im_prefs_from_screenname($screenname)
193 $user_im_prefs = User_im_prefs::pkeyGet(
194 array('transport' => $this->transport,
195 'screenname' => $this->normalize($screenname)));
196 if ($user_im_prefs) {
197 return $user_im_prefs;
205 * given a User, get their screenname
209 * @return string screenname of that user
211 function get_screenname($user)
213 $user_im_prefs = $this->get_user_im_prefs_from_user($user);
214 if ($user_im_prefs) {
215 return $user_im_prefs->screenname;
223 * given a User, get their User_im_prefs
227 * @return User_im_prefs user_im_prefs of that user
229 function get_user_im_prefs_from_user($user)
231 $user_im_prefs = User_im_prefs::pkeyGet(
232 array('transport' => $this->transport,
233 'user_id' => $user->id));
235 return $user_im_prefs;
240 //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - SENDING ========================\
242 * Send a message to a given screenname from the site
244 * @param string $screenname screenname to send the message to
245 * @param string $msg message contents to send
247 * @param boolean success
249 protected function send_from_site($screenname, $msg)
251 $text = '['.common_config('site', 'name') . '] ' . $msg;
252 $this->send_message($screenname, $text);
256 * send a confirmation code to a user
258 * @param string $screenname screenname sending to
259 * @param string $code the confirmation code
260 * @param User $user user sending to
262 * @return boolean success value
264 function send_confirmation_code($screenname, $code, $user)
266 $body = sprintf(_('User "%s" on %s has said that your %s screenname belongs to them. ' .
267 'If that\'s true, you can confirm by clicking on this URL: ' .
269 ' . (If you cannot click it, copy-and-paste it into the ' .
270 'address bar of your browser). If that user isn\'t you, ' .
271 'or if you didn\'t request this confirmation, just ignore this message.'),
272 $user->nickname, common_config('site', 'name'), $this->getDisplayName(), common_local_url('confirmaddress', array('code' => $code)));
274 return $this->send_message($screenname, $body);
278 * send a notice to all public listeners
280 * For notices that are generated on the local system (by users), we can optionally
281 * forward them to remote listeners by XMPP.
283 * @param Notice $notice notice to broadcast
285 * @return boolean success flag
288 function public_notice($notice)
290 // Now, users who want everything
292 // FIXME PRIV don't send out private messages here
293 // XXX: should we send out non-local messages if public,localonly
294 // = false? I think not
296 foreach ($this->public as $screenname) {
298 'Sending notice ' . $notice->id .
299 ' to public listener ' . $screenname,
301 $this->send_notice($screenname, $notice);
308 * broadcast a notice to all subscribers and reply recipients
310 * This function will send a notice to all subscribers on the local server
311 * who have IM addresses, and have IM notification enabled, and
312 * have this subscription enabled for IM. It also sends the notice to
313 * all recipients of @-replies who have IM addresses and IM notification
314 * enabled. This is really the heart of IM distribution in StatusNet.
316 * @param Notice $notice The notice to broadcast
318 * @return boolean success flag
321 function broadcast_notice($notice)
324 $ni = $notice->whoGets();
326 foreach ($ni as $user_id => $reason) {
327 $user = User::staticGet($user_id);
329 // either not a local user, or just not found
332 $user_im_prefs = $this->get_user_im_prefs_from_user($user);
333 if(!$user_im_prefs || !$user_im_prefs->notify){
338 case NOTICE_INBOX_SOURCE_REPLY:
339 if (!$user_im_prefs->replies) {
343 case NOTICE_INBOX_SOURCE_SUB:
344 $sub = Subscription::pkeyGet(array('subscriber' => $user->id,
345 'subscribed' => $notice->profile_id));
346 if (empty($sub) || !$sub->jabber) {
350 case NOTICE_INBOX_SOURCE_GROUP:
353 throw new Exception(sprintf(_("Unknown inbox source %d."), $reason));
357 'Sending notice ' . $notice->id . ' to ' . $user_im_prefs->screenname,
359 $this->send_notice($user_im_prefs->screenname, $notice);
360 $user_im_prefs->free();
367 * makes a plain-text formatted version of a notice, suitable for IM distribution
369 * @param Notice $notice notice being sent
371 * @return string plain-text version of the notice, with user nickname prefixed
374 function format_notice($notice)
376 $profile = $notice->getProfile();
377 return $profile->nickname . ': ' . $notice->content . ' [' . $notice->id . ']';
379 //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - RECEIVING ========================\
382 * Attempt to handle a message as a command
383 * @param User $user user the message is from
384 * @param string $body message text
385 * @return boolean true if the message was a command and was executed, false if it was not a command
387 protected function handle_command($user, $body)
389 $inter = new CommandInterpreter();
390 $cmd = $inter->handle_command($user, $body);
392 $chan = new IMChannel($this);
393 $cmd->execute($chan);
401 * Is some text an autoreply message?
402 * @param string $txt message text
403 * @return boolean true if autoreply
405 protected function is_autoreply($txt)
407 if (preg_match('/[\[\(]?[Aa]uto[-\s]?[Rr]e(ply|sponse)[\]\)]/', $txt)) {
409 } else if (preg_match('/^System: Message wasn\'t delivered. Offline storage size was exceeded.$/', $txt)) {
417 * Is some text an OTR message?
418 * @param string $txt message text
419 * @return boolean true if OTR
421 protected function is_otr($txt)
423 if (preg_match('/^\?OTR/', $txt)) {
431 * Helper for handling incoming messages
432 * Your incoming message handler will probably want to call this function
434 * @param string $from screenname the message was sent from
435 * @param string $message message contents
437 * @param boolean success
439 protected function handle_incoming($from, $notice_text)
441 $user = $this->get_user($from);
442 // For common_current_user to work
447 $this->send_from_site($from, 'Unknown user; go to ' .
448 common_local_url('imsettings') .
449 ' to add your address to your account');
450 common_log(LOG_WARNING, 'Message from unknown user ' . $from);
453 if ($this->handle_command($user, $notice_text)) {
454 common_log(LOG_INFO, "Command message by $from handled.");
456 } else if ($this->is_autoreply($notice_text)) {
457 common_log(LOG_INFO, 'Ignoring auto reply from ' . $from);
459 } else if ($this->is_otr($notice_text)) {
460 common_log(LOG_INFO, 'Ignoring OTR from ' . $from);
464 common_log(LOG_INFO, 'Posting a notice from ' . $user->nickname);
466 $this->add_notice($from, $user, $notice_text);
476 * Helper for handling incoming messages
477 * Your incoming message handler will probably want to call this function
479 * @param string $from screenname the message was sent from
480 * @param string $message message contents
482 * @param boolean success
484 protected function add_notice($screenname, $user, $body)
486 $body = trim(strip_tags($body));
487 $content_shortened = common_shorten_links($body);
488 if (Notice::contentTooLong($content_shortened)) {
489 $this->send_from_site($screenname, sprintf(_('Message too long - maximum is %1$d characters, you sent %2$d.'),
490 Notice::maxContent(),
491 mb_strlen($content_shortened)));
496 $notice = Notice::saveNew($user->id, $content_shortened, $this->transport);
497 } catch (Exception $e) {
498 common_log(LOG_ERR, $e->getMessage());
499 $this->send_from_site($from, $e->getMessage());
503 common_broadcast_notice($notice);
505 'Added notice ' . $notice->id . ' from user ' . $user->nickname);
510 //========================EVENT HANDLERS========================\
513 * Register notice queue handler
515 * @param QueueManager $manager
517 * @return boolean hook return
519 function onEndInitializeQueueManager($manager)
521 $manager->connect($this->transport . '-in', new ImReceiverQueueHandler($this), 'im');
522 $manager->connect($this->transport, new ImQueueHandler($this));
523 $manager->connect($this->transport . '-out', new ImSenderQueueHandler($this), 'im');
527 function onStartImDaemonIoManagers(&$classes)
529 //$classes[] = new ImManager($this); // handles sending/receiving/pings/reconnects
533 function onStartEnqueueNotice($notice, &$transports)
535 $profile = Profile::staticGet($notice->profile_id);
538 common_log(LOG_WARNING, 'Refusing to broadcast notice with ' .
539 'unknown profile ' . common_log_objstring($notice),
542 $transports[] = $this->transport;
548 function onEndShowHeadElements($action)
550 $aname = $action->trimmed('action');
552 if ($aname == 'shownotice') {
554 $user_im_prefs = new User_im_prefs();
555 $user_im_prefs->user_id = $action->profile->id;
556 $user_im_prefs->transport = $this->transport;
558 if ($user_im_prefs->find() && $user_im_prefs->fetch() && $user_im_prefs->microid && $action->notice->uri) {
559 $id = new Microid($this->microiduri($user_im_prefs->screenname),
560 $action->notice->uri);
561 $action->element('meta', array('name' => 'microid',
562 'content' => $id->toString()));
565 } else if ($aname == 'showstream') {
567 $user_im_prefs = new User_im_prefs();
568 $user_im_prefs->user_id = $action->user->id;
569 $user_im_prefs->transport = $this->transport;
571 if ($user_im_prefs->find() && $user_im_prefs->fetch() && $user_im_prefs->microid && $action->profile->profileurl) {
572 $id = new Microid($this->microiduri($user_im_prefs->screenname),
574 $action->element('meta', array('name' => 'microid',
575 'content' => $id->toString()));
580 function onNormalizeImScreenname($transport, &$screenname)
582 if($transport == $this->transport)
584 $screenname = $this->normalize($screenname);
589 function onValidateImScreenname($transport, $screenname, &$valid)
591 if($transport == $this->transport)
593 $valid = $this->validate($screenname);
598 function onGetImTransports(&$transports)
600 $transports[$this->transport] = array(
601 'display' => $this->getDisplayName(),
602 'daemon_screenname' => $this->daemon_screenname());
605 function onSendImConfirmationCode($transport, $screenname, $code, $user)
607 if($transport == $this->transport)
609 $this->send_confirmation_code($screenname, $code, $user);
614 function onUserDeleteRelated($user, &$tables)
616 $tables[] = 'User_im_prefs';
620 function initialize()
622 if(is_null($this->transport)){
623 throw new Exception('transport cannot be null');