This file is indexed.

/usr/include/gloox/adhoc.h is in libgloox-dev 1.0.11-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
/*
  Copyright (c) 2004-2014 by Jakob Schroeter <js@camaya.net>
  This file is part of the gloox library. http://camaya.net/gloox

  This software is distributed under a license. The full license
  agreement can be found in the file LICENSE in this distribution.
  This software may not be copied, modified, sold or distributed
  other than expressed in the named license agreement.

  This software is distributed without any warranty.
*/



#ifndef ADHOC_H__
#define ADHOC_H__

#include "dataform.h"
#include "disco.h"
#include "disconodehandler.h"
#include "discohandler.h"
#include "iqhandler.h"
#include "stanzaextension.h"
#include "mutex.h"

#include <string>
#include <list>
#include <map>

namespace gloox
{

  class ClientBase;
  class Stanza;
  class AdhocHandler;
  class AdhocCommandProvider;

  /**
   * @brief This class implements a provider for @xep{0050} (Ad-hoc Commands).
   *
   * The current, not complete, implementation is probably best suited for fire-and-forget
   * type of commands. Any additional feature, like multiple stages, etc., would have to be
   * added separately.
   *
   * To offer commands to remote entities, use this class as follows:<br>
   * Create a class that will handle command execution requests and derive it from
   * AdhocCommandProvider. Instantiate an Adhoc object and register your
   * AdhocCommandProvider-derived object with the Adhoc object using
   * registerAdhocCommandProvider(). The additional parameters to that method are the internal
   * name of the command as used in the code, and the public name of the command as it
   * will be shown to an end user:
   * @code
   * MyClass::someFunc()
   * {
   *   Adhoc* m_adhoc = new Adhoc( m_client );
   *
   *   // this might be a bot monitoring a weather station, for example
   *   m_adhoc->registerAdhocCommandProvider( this, "getTemp", "Retrieve current temperature" );
   *   m_adhoc->registerAdhocCommandProvider( this, "getPressure", "Retrieve current air pressure" );
   *   [...]
   * }
   * @endcode
   * In this example, MyClass is AdhocCommandProvider-derived so it is obviously the command handler, too.
   *
   * And that's about it you can do with the Adhoc class. Of course you can have a AdhocCommandProvider
   * handle more than one command, just register it with the Adhoc object for every desired command,
   * like shown above.
   *
   * What the Adhoc object does when you install a new command is tell the supplied Disco object
   * to advertise these commands to clients using the 'Service Discovery' protocol to learn about
   * this implementation's features. These clients can then call and execute the command. Of course you
   * are free to implement access restrictions to not let anyone mess with your bot, for example.
   * However, the commands offered using Service Discovery are publically visible in any case.
   *
   * To execute commands offered by a remote entity:<br>
   * ...TBC...
   *
   * XEP version: 1.2
   * @author Jakob Schroeter <js@camaya.net>
   */
  class GLOOX_API Adhoc : public DiscoNodeHandler, public DiscoHandler, public IqHandler
  {
    public:
      /**
       * @brief An abstraction of an Adhoc Command element (from Adhoc Commands, @xep{0050})
       * as a StanzaExtension.
       *
       * @author Jakob Schroeter <js@camaya.net>
       * @since 1.0
       */
      class GLOOX_API Command : public StanzaExtension
      {
        friend class Adhoc;

        public:

          /**
           * Specifies the action to undertake with the given command.
           */
          enum Action
          {
            Execute       =  1,     /**< The command should be executed or continue to be executed.
                                     * This is the default value. */
            Cancel        =  2,     /**< The command should be canceled. */
            Previous      =  4,     /**< The command should be digress to the previous stage of
                                     * execution. */
            Next          =  8,     /**< The command should progress to the next stage of
                                     * execution. */
            Complete      = 16,     /**< The command should be completed (if possible). */
            InvalidAction = 32      /**< The action is unknown or invalid. */
          };

          /**
           * Describes the current status of a command.
           */
          enum Status
          {
            Executing,              /**< The command is being executed. */
            Completed,              /**< The command has completed. The command session has ended. */
            Canceled,               /**< The command has been canceled. The command session has ended. */
            InvalidStatus           /**< The status is unknown or invalid. */
          };

          /**
           * An abstraction of a command note.
           *
           * @author Jakob Schroeter <js@camaya.net>
           * @since 1.0
           */
          class GLOOX_API Note
          {

            friend class Command;

            public:
              /**
               * Specifies the severity of a note.
               */
              enum Severity
              {
                Info,               /**< The note is informational only. This is not really an
                                     * exceptional condition. */
                Warning,            /**< The note indicates a warning. Possibly due to illogical
                                     * (yet valid) data. */
                Error,              /**< The note indicates an error. The text should indicate the
                                     * reason for the error. */
                InvalidSeverity     /**< The note type is unknown or invalid. */
              };

              /**
               * A convenience constructor.
               * @param sev The note's severity.
               * @param note The note's content.
               */
              Note( Severity sev, const std::string& note )
                : m_severity( sev ), m_note( note ) {}

              /**
               * Destructor.
               */
              ~Note() {}

              /**
               * Returns the note's severity.
               * @return The note's severity.
               */
              Severity severity() const { return m_severity; }

              /**
               * Returns the note's content.
               * @return The note's content.
               */
              const std::string& content() const { return m_note; }

              /**
               * Returns a Tag representation of the Note.
               * @return A Tag representation.
               */
              Tag* tag() const;

            private:
#ifdef ADHOC_COMMANDS_TEST
            public:
#endif
              /**
               * Constructs a new Note from the given Tag.
               * @param tag The Tag to parse.
               */
              Note( const Tag* tag );

              Severity m_severity;      /**< The note's severity. */
              std::string m_note;       /**< The note's content. */
          };

          /**
           * A list of command notes.
           */
          typedef std::list<const Note*> NoteList;

          /**
           * Creates a Command object that can be used to perform the provided Action.
           * This constructor is used best to continue execution of a multi stage command
           * (for which the session ID must be known).
           * @param node The node (command) to perform the action on.
           * @param sessionid The session ID of an already running adhoc command session.
           * @param action The action to perform.
           * @param form An optional DataForm to include in the request. Will be deleted in Command's
           * destructor.
           */
          Command( const std::string& node, const std::string& sessionid, Action action,
                   DataForm* form = 0 );

          /**
           * Creates a Command object that can be used to perform the provided Action.
           * This constructor is used best to reply to an execute request.
           * @param node The node (command) to perform the action on.
           * @param sessionid The (possibly newly created) session ID of the adhoc command session.
           * @param status The execution status.
           * @param form An optional DataForm to include in the reply. Will be deleted in Command's
           * destructor.
           */
          Command( const std::string& node, const std::string& sessionid, Status status,
                   DataForm* form = 0 );

          /**
           * Creates a Command object that can be used to perform the provided Action.
           * This constructor is used best to reply to a multi stage command that is not yet completed
           * (for which the session ID must be known).
           * @param node The node (command) to perform the action on.
           * @param sessionid The (possibly newly created) session ID of the adhoc command session.
           * @param status The execution status.
           * @param executeAction The action to execute.
           * @param allowedActions Allowed reply actions.
           * @param form An optional DataForm to include in the reply. Will be deleted in Command's
           * destructor.
           */
          Command( const std::string& node, const std::string& sessionid, Status status,
                   Action executeAction, int allowedActions = Complete,
                   DataForm* form = 0 );

          /**
           * Creates a Command object that can be used to perform the provided Action.
           * This constructor is used best to execute the initial step of a command
           * (single or multi stage).
           * @param node The node (command) to perform the action on.
           * @param action The action to perform.
           * @param form An optional DataForm to include in the request. Will be deleted in Command's
           * destructor.
           */
          Command( const std::string& node, Action action,
                   DataForm* form = 0 );

          /**
           * Creates a Command object from the given Tag.
           * @param tag A &lt;command&gt; tag in the adhoc commands' namespace.
           */
          Command( const Tag* tag = 0 );

          /**
           * Virtual destructor.
           */
          virtual ~Command();

          /**
           * Returns the node identifier (the command).
           * @return The node identifier.
           */
          const std::string& node() const { return m_node; }

          /**
           * Returns the command's session ID, if any.
           * @return The command's session ID.
           */
          const std::string& sessionID() const { return m_sessionid; }

          /**
           * Returns the execution status for a command. Only valid for execution
           * results.
           * @return The execution status for a command.
           */
          Status status() const { return m_status; }

          /**
           * Returns the command's action.
           * @return The command's action.
           */
          Action action() const { return m_action; }

          /**
           * Returns the ORed actions that are allowed to be executed on the
           * current stage.
           * @return An int containing the ORed actions.
           */
          int actions() const { return m_actions; }

          /**
           * Returns the list of notes associated with the command.
           * @return The list of notes.
           */
          const NoteList& notes() const { return m_notes; }

          /**
           * Use this function to add a note to the command.
           * @param note A pointer to a Note object. The Command will own
           * the Note.
           */
          void addNote( const Note* note ) { m_notes.push_back( note ); }

          /**
           * Returns the command's embedded DataForm.
           * @return The command's embedded DataForm. May be 0.
           */
          const DataForm* form() const { return m_form; }

          // reimplemented from StanzaExtension
          virtual const std::string& filterString() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* newInstance( const Tag* tag ) const
          {
            return new Command( tag );
          }

          // reimplemented from StanzaExtension
          virtual Tag* tag() const;

          // reimplemented from StanzaExtension
          virtual StanzaExtension* clone() const
          {
            Command* c = new Command();

            NoteList::const_iterator it = m_notes.begin();
            for( ; it != m_notes.end(); ++it )
              c->m_notes.push_back( new Note( *(*it) ) );

            c->m_node = m_node;
            c->m_sessionid = m_sessionid;
            c->m_form = m_form ? static_cast<DataForm*>( m_form->clone() ) : 0;
            c->m_action = m_action;
            c->m_status = m_status;
            c->m_actions = m_actions;

            return c;
          }

        private:
#ifdef ADHOC_COMMANDS_TEST
        public:
#endif
          NoteList m_notes;

          std::string m_node;
          std::string m_sessionid;
          DataForm* m_form;
          Action m_action;
          Status m_status;
          int m_actions;
      };

      /**
       * Constructor.
       * Creates a new Adhoc client that registers as IqHandler with a ClientBase.
       * @param parent The ClientBase used for XMPP communication.
       */
      Adhoc( ClientBase* parent );

      /**
       * Virtual destructor.
       */
      virtual ~Adhoc();

      /**
       * This function queries the given remote entity for Adhoc Commands support.
       * @param remote The remote entity's JID.
       * @param ah The object handling the result of this request.
       * @param context A user defined context.
       */
      void checkSupport( const JID& remote, AdhocHandler* ah, int context = 0 );

      /**
       * Retrieves a list of commands from the remote entity. You should check whether the remote
       * entity actually supports Adhoc Commands by means of checkSupport().
       * @param remote The remote entity's JID.
       * @param ah The object handling the result of this request.
       * @param context A user defined context.
       */
      void getCommands( const JID& remote, AdhocHandler* ah, int context = 0 );

      /**
       * Executes or continues the given command on the given remote entity.
       * To construct the @c command object, it is recommended to use either
       * Command( const std::string&, Action ) to begin execution of a command, or
       * Command( const std::string&, const std::string&, Action ) to continue execution
       * of a command.
       * @param remote The remote entity's JID.
       * @param command The command to execute.
       * @param ah The object handling the result of this request.
       * @param context A user defined context.
       */
      void execute( const JID& remote, const Adhoc::Command* command, AdhocHandler* ah, int context = 0 );

      /**
       * Use this function to respond to an execution request submitted by means
       * of AdhocCommandProvider::handleAdhocCommand().
       * It is recommended to use
       * Command( const std::string&, const std::string&, Status, DataForm* )
       * to construct the @c command object.
       * Optionally, an Error object can be included. In that case the IQ sent is of type @c error.
       * @param remote The requester's JID.
       * @param command The response. The Adhoc object will own and delete the
       * command object pointed to.
       * @param error An optional Error obejct to include.
       */
      void respond( const JID& remote, const Adhoc::Command* command, const Error* error = 0 );

      /**
       * Using this function, you can register a AdhocCommandProvider -derived object as
       * handler for a specific Ad-hoc Command as defined in @xep{0050}.
       * @param acp The object to register as handler for the specified command.
       * @param command The node name of the command. Will be announced in disco#items.
       * @param name The natural-language name of the command. Will be announced in disco#items.
       */
      void registerAdhocCommandProvider( AdhocCommandProvider* acp, const std::string& command,
                                         const std::string& name );

      /**
       * Use this function to unregister an adhoc command previously registered using
       * registerAdhocCommandProvider().
       * @param command The command to unregister.
       */
      void removeAdhocCommandProvider( const std::string& command );

      // reimplemented from DiscoNodeHandler
      virtual StringList handleDiscoNodeFeatures( const JID& from, const std::string& node );

      // reimplemented from DiscoNodeHandler
      virtual Disco::IdentityList handleDiscoNodeIdentities( const JID& from,
          const std::string& node );

      // reimplemented from DiscoNodeHandler
      virtual Disco::ItemList handleDiscoNodeItems( const JID& from, const JID& to, const std::string& node );

      // reimplemented from IqHandler
      virtual bool handleIq( const IQ& iq );

      // reimplemented from IqHandler
      virtual void handleIqID( const IQ& iq, int context );

      // reimplemented from DiscoHandler
      virtual void handleDiscoInfo( const JID& from, const Disco::Info& info, int context );

      // reimplemented from DiscoHandler
      virtual void handleDiscoItems( const JID& from, const Disco::Items& items, int context );

      // reimplemented from DiscoHandler
      virtual void handleDiscoError( const JID& from, const Error* error, int context );

    private:
#ifdef ADHOC_TEST
    public:
#endif
      typedef std::map<const std::string, AdhocCommandProvider*> AdhocCommandProviderMap;
      AdhocCommandProviderMap m_adhocCommandProviders;

      enum AdhocContext
      {
        CheckAdhocSupport,
        FetchAdhocCommands,
        ExecuteAdhocCommand
      };

      struct TrackStruct
      {
        JID remote;
        AdhocContext context;
        std::string session;
        AdhocHandler* ah;
        int handlerContext;
      };
      typedef std::map<std::string, TrackStruct> AdhocTrackMap;
      AdhocTrackMap m_adhocTrackMap;
      util::Mutex m_adhocTrackMapMutex;

      ClientBase* m_parent;

      StringMap m_items;
      StringMap m_activeSessions;

  };

}

#endif // ADHOC_H__