]> git.mxchange.org Git - quix0rs-gnu-social.git/blob - lib/implugin.php
Same goes to onStartShowAside() which has 'Action' as type-hint.
[quix0rs-gnu-social.git] / lib / implugin.php
1 <?php
2 /**
3  * StatusNet, the distributed open-source microblogging tool
4  *
5  * Superclass for plugins that do instant messaging
6  *
7  * PHP version 5
8  *
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.
13  *
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.
18  *
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/>.
21  *
22  * @category  Plugin
23  * @package   StatusNet
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/
27  */
28
29 if (!defined('STATUSNET') && !defined('LACONICA')) {
30     exit(1);
31 }
32
33 /**
34  * Superclass for plugins that do authentication
35  *
36  * Implementations will likely want to override onStartIoManagerClasses() so that their
37  *   IO manager is used
38  *
39  * @category Plugin
40  * @package  StatusNet
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/
44  */
45 abstract class ImPlugin extends Plugin
46 {
47     //name of this IM transport
48     public $transport = null;
49     //list of screennames that should get all public notices
50     public $public = array();
51
52     /**
53      * normalize a screenname for comparison
54      *
55      * @param string $screenname screenname to normalize
56      *
57      * @return string an equivalent screenname in normalized form
58      */
59     abstract function normalize($screenname);
60
61     /**
62      * validate (ensure the validity of) a screenname
63      *
64      * @param string $screenname screenname to validate
65      *
66      * @return boolean
67      */
68     abstract function validate($screenname);
69
70     /**
71      * get the internationalized/translated display name of this IM service
72      *
73      * @return string
74      */
75     abstract function getDisplayName();
76
77     /**
78      * send a single notice to a given screenname
79      * The implementation should put raw data, ready to send, into the outgoing
80      *   queue using enqueueOutgoingRaw()
81      *
82      * @param string $screenname screenname to send to
83      * @param Notice $notice notice to send
84      *
85      * @return boolean success value
86      */
87     function sendNotice($screenname, Notice $notice)
88     {
89         return $this->sendMessage($screenname, $this->formatNotice($notice));
90     }
91
92     /**
93      * send a message (text) to a given screenname
94      * The implementation should put raw data, ready to send, into the outgoing
95      *   queue using enqueueOutgoingRaw()
96      *
97      * @param string $screenname screenname to send to
98      * @param Notice $body text to send
99      *
100      * @return boolean success value
101      */
102     abstract function sendMessage($screenname, $body);
103
104     /**
105      * receive a raw message
106      * Raw IM data is taken from the incoming queue, and passed to this function.
107      * It should parse the raw message and call handleIncoming()
108      *
109      * Returning false may CAUSE REPROCESSING OF THE QUEUE ITEM, and should
110      * be used for temporary failures only. For permanent failures such as
111      * unrecognized addresses, return true to indicate your processing has
112      * completed.
113      *
114      * @param object $data raw IM data
115      *
116      * @return boolean true if processing completed, false for temporary failures
117      */
118     abstract function receiveRawMessage($data);
119
120     /**
121      * get the screenname of the daemon that sends and receives message for this service
122      *
123      * @return string screenname of this plugin
124      */
125     abstract function daemonScreenname();
126
127     /**
128      * get the microid uri of a given screenname
129      *
130      * @param string $screenname screenname
131      *
132      * @return string microid uri
133      */
134     function microiduri($screenname)
135     {
136         return $this->transport . ':' . $screenname;
137     }
138     //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - MISC ========================\
139
140     /**
141      * Put raw message data (ready to send) into the outgoing queue
142      *
143      * @param object $data
144      */
145     function enqueueOutgoingRaw($data)
146     {
147         $qm = QueueManager::get();
148         $qm->enqueue($data, $this->transport . '-out');
149     }
150
151     /**
152      * Put raw message data (received, ready to be processed) into the incoming queue
153      *
154      * @param object $data
155      */
156     function enqueueIncomingRaw($data)
157     {
158         $qm = QueueManager::get();
159         $qm->enqueue($data, $this->transport . '-in');
160     }
161
162     /**
163      * given a screenname, get the corresponding user
164      *
165      * @param string $screenname
166      *
167      * @return User user
168      */
169     function getUser($screenname)
170     {
171         $user_im_prefs = $this->getUserImPrefsFromScreenname($screenname);
172         if($user_im_prefs){
173             $user = User::getKV('id', $user_im_prefs->user_id);
174             $user_im_prefs->free();
175             return $user;
176         }else{
177             return false;
178         }
179     }
180
181     /**
182      * given a screenname, get the User_im_prefs object for this transport
183      *
184      * @param string $screenname
185      *
186      * @return User_im_prefs user_im_prefs
187      */
188     function getUserImPrefsFromScreenname($screenname)
189     {
190         $user_im_prefs = User_im_prefs::pkeyGet(
191             array('transport' => $this->transport,
192                   'screenname' => $this->normalize($screenname)));
193         if ($user_im_prefs) {
194             return $user_im_prefs;
195         } else {
196             return false;
197         }
198     }
199
200     /**
201      * given a User, get their screenname
202      *
203      * @param User $user
204      *
205      * @return string screenname of that user
206      */
207     function getScreenname($user)
208     {
209         $user_im_prefs = $this->getUserImPrefsFromUser($user);
210         if ($user_im_prefs) {
211             return $user_im_prefs->screenname;
212         } else {
213             return false;
214         }
215     }
216
217     /**
218      * given a User, get their User_im_prefs
219      *
220      * @param User $user
221      *
222      * @return User_im_prefs user_im_prefs of that user
223      */
224     function getUserImPrefsFromUser($user)
225     {
226         $user_im_prefs = User_im_prefs::pkeyGet(
227             array('transport' => $this->transport,
228                   'user_id' => $user->id));
229         if ($user_im_prefs){
230             return $user_im_prefs;
231         } else {
232             return false;
233         }
234     }
235     //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - SENDING ========================\
236     /**
237      * Send a message to a given screenname from the site
238      *
239      * @param string $screenname screenname to send the message to
240      * @param string $msg message contents to send
241      *
242      * @param boolean success
243      */
244     protected function sendFromSite($screenname, $msg)
245     {
246         $text = '['.common_config('site', 'name') . '] ' . $msg;
247         $this->sendMessage($screenname, $text);
248     }
249
250     /**
251      * Send a confirmation code to a user
252      *
253      * @param string $screenname screenname sending to
254      * @param string $code the confirmation code
255      * @param User $user user sending to
256      *
257      * @return boolean success value
258      */
259     function sendConfirmationCode($screenname, $code, $user)
260     {
261         // TRANS: Body text for confirmation code e-mail.
262         // TRANS: %1$s is a user nickname, %2$s is the StatusNet sitename,
263         // TRANS: %3$s is the display name of an IM plugin.
264         $body = sprintf(_('User "%1$s" on %2$s has said that your %3$s screenname belongs to them. ' .
265           'If that is true, you can confirm by clicking on this URL: ' .
266           '%4$s' .
267           ' . (If you cannot click it, copy-and-paste it into the ' .
268           'address bar of your browser). If that user is not you, ' .
269           'or if you did not request this confirmation, just ignore this message.'),
270           $user->nickname, common_config('site', 'name'), $this->getDisplayName(), common_local_url('confirmaddress', null, array('code' => $code)));
271
272         return $this->sendMessage($screenname, $body);
273     }
274
275     /**
276      * send a notice to all public listeners
277      *
278      * For notices that are generated on the local system (by users), we can optionally
279      * forward them to remote listeners by XMPP.
280      *
281      * @param Notice $notice notice to broadcast
282      *
283      * @return boolean success flag
284      */
285
286     function publicNotice($notice)
287     {
288         // Now, users who want everything
289
290         // FIXME PRIV don't send out private messages here
291         // XXX: should we send out non-local messages if public,localonly
292         // = false? I think not
293
294         foreach ($this->public as $screenname) {
295             common_log(LOG_INFO,
296                        'Sending notice ' . $notice->id .
297                        ' to public listener ' . $screenname,
298                        __FILE__);
299             $this->sendNotice($screenname, $notice);
300         }
301
302         return true;
303     }
304
305     /**
306      * broadcast a notice to all subscribers and reply recipients
307      *
308      * This function will send a notice to all subscribers on the local server
309      * who have IM addresses, and have IM notification enabled, and
310      * have this subscription enabled for IM. It also sends the notice to
311      * all recipients of @-replies who have IM addresses and IM notification
312      * enabled. This is really the heart of IM distribution in StatusNet.
313      *
314      * @param Notice $notice The notice to broadcast
315      *
316      * @return boolean success flag
317      */
318
319     function broadcastNotice($notice)
320     {
321         $ni = $notice->whoGets();
322
323         foreach ($ni as $user_id => $reason) {
324             $user = User::getKV($user_id);
325             if (empty($user)) {
326                 // either not a local user, or just not found
327                 continue;
328             }
329             $user_im_prefs = $this->getUserImPrefsFromUser($user);
330             if(!$user_im_prefs || !$user_im_prefs->notify){
331                 continue;
332             }
333
334             switch ($reason) {
335             case NOTICE_INBOX_SOURCE_REPLY:
336                 if (!$user_im_prefs->replies) {
337                     continue 2;
338                 }
339                 break;
340             case NOTICE_INBOX_SOURCE_SUB:
341                 $sub = Subscription::pkeyGet(array('subscriber' => $user->id,
342                                                    'subscribed' => $notice->profile_id));
343                 if (empty($sub) || !$sub->jabber) {
344                     continue 2;
345                 }
346                 break;
347             case NOTICE_INBOX_SOURCE_GROUP:
348                 break;
349             default:
350                 // TRANS: Exception thrown when trying to deliver a notice to an unknown inbox.
351                 // TRANS: %d is the unknown inbox ID (number).
352                 throw new Exception(sprintf(_('Unknown inbox source %d.'), $reason));
353             }
354
355             common_log(LOG_INFO,
356                        'Sending notice ' . $notice->id . ' to ' . $user_im_prefs->screenname,
357                        __FILE__);
358             $this->sendNotice($user_im_prefs->screenname, $notice);
359             $user_im_prefs->free();
360         }
361
362         return true;
363     }
364
365     /**
366      * makes a plain-text formatted version of a notice, suitable for IM distribution
367      *
368      * @param Notice  $notice  notice being sent
369      *
370      * @return string plain-text version of the notice, with user nickname prefixed
371      */
372
373     protected function formatNotice(Notice $notice)
374     {
375         $profile = $notice->getProfile();
376
377         try {
378             $parent = $notice->getParent();
379             $orig_profile = $parent->getProfile();
380             $nicknames = sprintf('%1$s => %2$s', $profile->nickname, $orig_profile->nickname);
381         } catch (Exception $e) {
382             $nicknames = $profile->nickname;
383         }
384
385         return sprintf('%1$s: %2$s [%3$u]', $nicknames, $notice->content, $notice->id);
386     }
387     //========================UTILITY FUNCTIONS USEFUL TO IMPLEMENTATIONS - RECEIVING ========================\
388
389     /**
390      * Attempt to handle a message as a command
391      * @param User $user user the message is from
392      * @param string $body message text
393      * @return boolean true if the message was a command and was executed, false if it was not a command
394      */
395     protected function handleCommand($user, $body)
396     {
397         $inter = new CommandInterpreter();
398         $cmd = $inter->handle_command($user, $body);
399         if ($cmd) {
400             $chan = new IMChannel($this);
401             $cmd->execute($chan);
402             return true;
403         } else {
404             return false;
405         }
406     }
407
408     /**
409      * Is some text an autoreply message?
410      * @param string $txt message text
411      * @return boolean true if autoreply
412      */
413     protected function isAutoreply($txt)
414     {
415         if (preg_match('/[\[\(]?[Aa]uto[-\s]?[Rr]e(ply|sponse)[\]\)]/', $txt)) {
416             return true;
417         } else if (preg_match('/^System: Message wasn\'t delivered. Offline storage size was exceeded.$/', $txt)) {
418             return true;
419         } else {
420             return false;
421         }
422     }
423
424     /**
425      * Is some text an OTR message?
426      * @param string $txt message text
427      * @return boolean true if OTR
428      */
429     protected function isOtr($txt)
430     {
431         if (preg_match('/^\?OTR/', $txt)) {
432             return true;
433         } else {
434             return false;
435         }
436     }
437
438     /**
439      * Helper for handling incoming messages
440      * Your incoming message handler will probably want to call this function
441      *
442      * @param string $from screenname the message was sent from
443      * @param string $message message contents
444      *
445      * @param boolean success
446      */
447     protected function handleIncoming($from, $notice_text)
448     {
449         $user = $this->getUser($from);
450         // For common_current_user to work
451         global $_cur;
452         $_cur = $user;
453
454         if (!$user) {
455             $this->sendFromSite($from, 'Unknown user; go to ' .
456                              common_local_url('imsettings') .
457                              ' to add your address to your account');
458             common_log(LOG_WARNING, 'Message from unknown user ' . $from);
459             return;
460         }
461         if ($this->handleCommand($user, $notice_text)) {
462             common_log(LOG_INFO, "Command message by $from handled.");
463             return;
464         } else if ($this->isAutoreply($notice_text)) {
465             common_log(LOG_INFO, 'Ignoring auto reply from ' . $from);
466             return;
467         } else if ($this->isOtr($notice_text)) {
468             common_log(LOG_INFO, 'Ignoring OTR from ' . $from);
469             return;
470         } else {
471
472             common_log(LOG_INFO, 'Posting a notice from ' . $user->nickname);
473
474             $this->addNotice($from, $user, $notice_text);
475         }
476
477         $user->free();
478         unset($user);
479         unset($_cur);
480         unset($message);
481     }
482
483     /**
484      * Helper for handling incoming messages
485      * Your incoming message handler will probably want to call this function
486      *
487      * @param string $from screenname the message was sent from
488      * @param string $message message contents
489      *
490      * @param boolean success
491      */
492     protected function addNotice($screenname, $user, $body)
493     {
494         $body = trim(strip_tags($body));
495         $content_shortened = common_shorten_links($body);
496         if (Notice::contentTooLong($content_shortened)) {
497           $this->sendFromSite($screenname,
498                               // TRANS: Message given when a status is too long. %1$s is the maximum number of characters,
499                               // TRANS: %2$s is the number of characters sent (used for plural).
500                               sprintf(_m('Message too long - maximum is %1$d character, you sent %2$d.',
501                                          'Message too long - maximum is %1$d characters, you sent %2$d.',
502                                          Notice::maxContent()),
503                                       Notice::maxContent(),
504                                       mb_strlen($content_shortened)));
505           return;
506         }
507
508         try {
509             $notice = Notice::saveNew($user->id, $content_shortened, $this->transport);
510         } catch (Exception $e) {
511             common_log(LOG_ERR, $e->getMessage());
512             $this->sendFromSite($from, $e->getMessage());
513             return;
514         }
515
516         common_log(LOG_INFO,
517                    'Added notice ' . $notice->id . ' from user ' . $user->nickname);
518         $notice->free();
519         unset($notice);
520     }
521
522     //========================EVENT HANDLERS========================\
523
524     /**
525      * Register notice queue handler
526      *
527      * @param QueueManager $manager
528      *
529      * @return boolean hook return
530      */
531     function onEndInitializeQueueManager($manager)
532     {
533         $manager->connect($this->transport . '-in', new ImReceiverQueueHandler($this), 'im');
534         $manager->connect($this->transport, new ImQueueHandler($this));
535         $manager->connect($this->transport . '-out', new ImSenderQueueHandler($this), 'im');
536         return true;
537     }
538
539     function onStartImDaemonIoManagers(&$classes)
540     {
541         //$classes[] = new ImManager($this); // handles sending/receiving/pings/reconnects
542         return true;
543     }
544
545     function onStartEnqueueNotice(Notice $notice, array &$transports)
546     {
547         $profile = Profile::getKV($notice->profile_id);
548
549         if (!$profile) {
550             common_log(LOG_WARNING, 'Refusing to broadcast notice with ' .
551                        'unknown profile ' . common_log_objstring($notice),
552                        __FILE__);
553         }else{
554             $transports[] = $this->transport;
555         }
556
557         return true;
558     }
559
560     function onEndShowHeadElements($action)
561     {
562         $aname = $action->trimmed('action');
563
564         if ($aname == 'shownotice') {
565
566             $user_im_prefs = new User_im_prefs();
567             $user_im_prefs->user_id = $action->profile->id;
568             $user_im_prefs->transport = $this->transport;
569
570             if ($user_im_prefs->find() && $user_im_prefs->fetch() && $user_im_prefs->microid && $action->notice->uri) {
571                 $id = new Microid($this->microiduri($user_im_prefs->screenname),
572                                   $action->notice->uri);
573                 $action->element('meta', array('name' => 'microid',
574                                              'content' => $id->toString()));
575             }
576
577         } else if ($aname == 'showstream') {
578
579             $user_im_prefs = new User_im_prefs();
580             $user_im_prefs->user_id = $action->user->id;
581             $user_im_prefs->transport = $this->transport;
582
583             if ($user_im_prefs->find() && $user_im_prefs->fetch() && $user_im_prefs->microid && $action->profile->profileurl) {
584                 $id = new Microid($this->microiduri($user_im_prefs->screenname),
585                                   $action->selfUrl());
586                 $action->element('meta', array('name' => 'microid',
587                                                'content' => $id->toString()));
588             }
589         }
590     }
591
592     function onNormalizeImScreenname($transport, &$screenname)
593     {
594         if($transport == $this->transport)
595         {
596             $screenname = $this->normalize($screenname);
597             return false;
598         }
599     }
600
601     function onValidateImScreenname($transport, $screenname, &$valid)
602     {
603         if($transport == $this->transport)
604         {
605             $valid = $this->validate($screenname);
606             return false;
607         }
608     }
609
610     function onGetImTransports(&$transports)
611     {
612         $transports[$this->transport] = array(
613             'display' => $this->getDisplayName(),
614             'daemonScreenname' => $this->daemonScreenname());
615     }
616
617     function onSendImConfirmationCode($transport, $screenname, $code, $user)
618     {
619         if($transport == $this->transport)
620         {
621             $this->sendConfirmationCode($screenname, $code, $user);
622             return false;
623         }
624     }
625
626     function onUserDeleteRelated($user, &$tables)
627     {
628         $tables[] = 'User_im_prefs';
629         return true;
630     }
631
632     function onHaveImPlugin(&$haveImPlugin) {
633         $haveImPlugin = true; // set flag true (we're loaded, after all!)
634         return false; // stop looking
635     }
636
637     function initialize()
638     {
639         if( ! common_config('queue', 'enabled'))
640         {
641             // TRANS: Server exception thrown trying to initialise an IM plugin without meeting all prerequisites.
642             throw new ServerException(_('Queueing must be enabled to use IM plugins.'));
643         }
644
645         if(is_null($this->transport)){
646             // TRANS: Server exception thrown trying to initialise an IM plugin without a transport method.
647             throw new ServerException(_('Transport cannot be null.'));
648         }
649     }
650 }