This file is indexed.

/usr/include/wvstreams/wvencoder.h is in libwvstreams-dev 4.6.1-5.

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
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
/* -*- Mode: C++ -*-
 * Worldvisions Weaver Software:
 *   Copyright (C) 1997-2002 Net Integration Technologies, Inc.
 *
 * A top-level data encoder class and a few useful encoders.
 */
#ifndef __WVENCODER_H
#define __WVENCODER_H

#include "wvbuf.h"
#include "wvlinklist.h"
#include "wvstring.h"

/**
 * The base encoder class.
 * 
 * Encoders read data from an input buffer, transform it in some
 * way, then write the results to an output buffer.  The resulting
 * data may be of a different size or data type, and may or may
 * not depend on previous data.
 * 
 * Encoders may or may not possess the following characteristics:
 * 
 *  - Statefulness: encoding of successive input elements may
 *     depend on previous one
 *  - Error states: encoding may enter an error state indicated
 *     by isok() == false due to problems detected
 *     in the input, or by the manner in which the encoder has
 *     been user
 *  - Minimum input block size: data will not be drawn from the
 *     input buffer until enough is available or the encoder
 *     is flushed
 *  - Minimum output block size: data will not be written to the
 *     output buffer until enough free space is available
 *  - Synchronization boundaries: data is process or generated
 *     in chunks which can be manipulated independently of any
 *     others, in which case flush() may cause the encoder to
 *     produce such a boundary in its output
 *  - Recognition of end-of-data mark: a special sequence marks
 *     the end of input, after which the encoder transitions to
 *     isfinished() == true
 *  - Generation of end-of-data mark: a special sequence marks
 *     the end of output when the encoder transitions to
 *     isfinished() == true, usually by an explicit
 *     call to finish()
 *  - Reset support: the encoder may be reset to its initial
 *     state and thereby recycled at minimum cost
 * 
 * 
 * Helper functions are provided for encoding data from plain
 * memory buffers and from strings.  Some have no encode(...)
 * equivalent because they cannot incrementally encode from
 * the input, hence they always use the flush option.
 * 
 * The 'mem' suffix has been tacked on to these functions to
 * resolve ambiguities dealing with 'char *' that should be
 * promoted to WvString.  For instance, consider the signatures
 * of strflushmem(const void*, size_t) and strflushstr(WvStringParm,
 * bool).
 * 
 * Another reason for these suffixes is to simplify overloading
 * the basic methods in subclasses since C++ would require the
 * subclass to redeclare all of the other signatures for
 * an overloaded method.
 * 
 */
class WvEncoder
{
protected:
    bool okay; /*!< false iff setnotok() was called */
    bool finished; /*!< true iff setfinished()/finish() was called */
    WvString errstr; /*!< the error message */

public:
    /** Creates a new WvEncoder. */
    WvEncoder();

    /** Destroys the encoder.  Unflushed data is lost. */
    virtual ~WvEncoder();
    
    /**
     * Returns true if the encoder has not encountered an error.
     * 
     * This should only be used to record permanent failures.
     * Transient errors (eg. bad block, but recoverable) should be
     * detected in a different fashion.
     * 
     * Returns: true if the encoder is ok
     */
    bool isok() const
        { return okay && _isok(); }

    /**
     * Returns true if the encoder can no longer encode data.
     * 
     * This will be set when the encoder detects and end-of-data
     * mark in its input, or when finish() is called.
     * 
     * Returns: true if the encoder is finished
     */
    bool isfinished() const
        { return finished || _isfinished(); }

    /**
     * Returns an error message if any is available.
     *
     * Returns: the error message, or the null string is isok() == true
     */
    WvString geterror() const;

    /**
     * Reads data from the input buffer, encodes it, and writes the result
     * to the output buffer.
     * 
     * If flush == true, the input buffer will be drained and the output
     * buffer will contain all of the encoded data including any that
     * might have been buffered internally from previous calls.  Thus it
     * is possible that new data will be written to the output buffer even
     * though the input buffer was empty when encode() was called.  If the
     * buffer could not be fully drained because there was insufficient
     * data, this function returns false and leaves the remaining unflushed
     * data in the buffer.
     * 
     * If flush == false, the encoder will read and encode as much data
     * as possible (or as is convenient) from the input buffer and store
     * the results in the output buffer.  Partial results may be buffered
     * internally by the encoder to be written to the output buffer later
     * when the encoder is flushed.
     * 
     * If finish = true, the encode() will be followed up by a call to
     * finish().  The return values will be ANDed together to yield the
     * final result.  Most useful when flush is also true.
     *
     * If a permanent error occurs, then isok() will return false, this
     * function will return false and the input buffer will be left in an
     * undefined state.
     * 
     * If a recoverable error occurs, the encoder should discard the
     * problematic data from the input buffer and return false from this
     * function, but isok() will remain true.
     * 
     * A stream might become isfinished() == true if an encoder-
     * specific end-of-data marker was detected in the input.
     * 
     * "inbuf" is the input buffer
     * "outbuf" is the output buffer
     * "flush" is if true, flushes the encoder
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     * @see _encode for the actual implementation
     */
    bool encode(WvBuf &inbuf, WvBuf &outbuf, bool flush = false,
        bool finish = false);

    /**
     * Flushes the encoder and optionally finishes it.
     *
     * "inbuf" is the input buffer
     * "outbuf" is the output buffer
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */
    bool flush(WvBuf &inbuf, WvBuf &outbuf,
        bool finish = false)
        { return encode(inbuf, outbuf, true, finish); }

    /**
     * Tells the encoder that NO MORE DATA will ever be encoded.
     * 
     * The encoder will flush out any internally buffered data
     * and write out whatever end-of-data marking it needs to the
     * supplied output buffer before returning.
     * 
     * Clients should invoke flush() on the input buffer before
     * finish() if the input buffer was not yet empty.
     * 
     * It is safe to call this function multiple times.
     * The implementation will simply return isok() and do nothing else.
     * 
     * "outbuf" is the output buffer
     * Returns: true on success
     * @see _finish for the actual implementation
     */
    bool finish(WvBuf &outbuf);

    /**
     * Asks an encoder to reset itself to its initial state at
     * creation time, if supported.
     * 
     * This function may be called at any time, even if
     * isok() == false, or isfinished() == true.
     * 
     * If the behaviour is not supported or an error occurs,
     * then false is returned and afterwards isok() == false.
     * 
     * Returns: true on success
     * @see _reset for the actual implementation
     */
    bool reset();

    /**
     * Flushes data through the encoder from a string to a buffer.
     *
     * "instr" is the input string
     * "outbuf" is the output buffer
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */
    bool flushstrbuf(WvStringParm instr, WvBuf &outbuf,
        bool finish = false);
        
    /**
     * Flushes data through the encoder from a string to a string.
     * 
     * The output data is appended to the target string.
     * 
     * "instr" is the input string
     * "outstr" is the output string
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */
    bool flushstrstr(WvStringParm instr, WvString &outstr,
        bool finish = false);

    /**
     * Encodes data from a buffer to a string.
     * 
     * The output data is appended to the target string.
     * 
     * "inbuf" is the input buffer
     * "outstr" is the output string
     * "flush" is if true, flushes the encoder
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */   
    bool encodebufstr(WvBuf &inbuf, WvString &outstr,
        bool flush = false, bool finish = false);

    /**
     * Flushes data through the encoder from a buffer to a string.
     * 
     * The output data is appended to the target string.
     * 
     * "inbuf" is the input buffer
     * "outstr" is the output string
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */   
    bool flushbufstr(WvBuf &inbuf, WvString &outstr,
        bool finish = false)
        { return encodebufstr(inbuf, outstr, true, finish); }
    
    /**
     * Flushes data through the encoder from a string to a string.
     *
     * "inbuf" is the input buffer
     * "finish" is if true, calls finish() on success
     * Returns: the resulting encoded string, does not signal errors
     */   
    WvString strflushstr(WvStringParm instr, bool finish = false);
    
    /**
     * Flushes data through the encoder from a buffer to a string.
     *
     * "inbuf" is the input buffer
     * "finish" is if true, calls finish() on success
     * Returns: the resulting encoded string, does not signal errors
     */   
    WvString strflushbuf(WvBuf &inbuf, bool finish = false);

    /**
     * Flushes data through the encoder from memory to a buffer.
     *
     * "inmem" is the input data pointer
     * "inlen" is the input data length
     * "outbuf" is the output buffer
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */
    bool flushmembuf(const void *inmem, size_t inlen, WvBuf &outbuf,
        bool finish = false);
        
    /**
     * Flushes data through the encoder from memory to memory.
     * 
     * The outlen parameter specifies by reference
     * the length of the output buffer.  It is updated in place to
     * reflect the number of bytes copied to the output buffer.
     * If the buffer was too small to hold the data, the overflow
     * bytes will be discarded and false will be returned.
     * 
     * "inmem" is the input data pointer
     * "inlen" is the input data length
     * "outmem" is the output data pointer
     * "outlen" is the output data length, by reference
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */
    bool flushmemmem(const void *inmem, size_t inlen, void *outmem,
        size_t *outlen, bool finish = false);
        
    /**
     * Encodes data from a buffer to memory.
     * 
     * The outlen parameter specifies by reference
     * the length of the output buffer.  It is updated in place to
     * reflect the number of bytes copied to the output buffer.
     * If the buffer was too small to hold the data, the overflow
     * bytes will be discarded and false will be returned.
     * 
     * "inmem" is the input data pointer
     * "inlen" is the input data length
     * "outmem" is the output data pointer
     * "outlen" is the output data length, by reference
     * "flush" is if true, flushes the encoder
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */
    bool encodebufmem(WvBuf &inbuf, void *outmem, size_t *outlen,
        bool flush = false, bool finish = false);   
        
    /**
     * Flushes data through the encoder from a buffer to memory.
     * 
     * The outlen parameter specifies by reference
     * the length of the output buffer.  It is updated in place to
     * reflect the number of bytes copied to the output buffer.
     * If the buffer was too small to hold the data, the overflow
     * bytes will be discarded and false will be returned.
     * 
     * "inbuf" is the input buffer
     * "outmem" is the output data pointer
     * "outlen" is the output data length, by reference
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */
    bool flushbufmem(WvBuf &inbuf, void *outmem, size_t *outlen,
        bool finish = false)
        { return encodebufmem(inbuf, outmem, outlen, true, finish); }

    /**
     * Flushes data through the encoder from a string to memory.
     * 
     * The outlen parameter specifies by reference
     * the length of the output buffer.  It is updated in place to
     * reflect the number of bytes copied to the output buffer.
     * If the buffer was too small to hold the data, the overflow
     * bytes will be discarded and false will be returned.
     * 
     * "instr" is the input string
     * "outmem" is the output data pointer
     * "outlen" is the output data length, by reference
     * "finish" is if true, calls finish() on success
     * Returns: true on success
     */
    bool flushstrmem(WvStringParm instr, void *outmem, size_t *outlen,
        bool finish = false);

    /**
     * Flushes data through the encoder from memory to a string.
     *
     * "inmem" is the input data pointer
     * "inlen" is the input data length
     * "finish" is if true, calls finish() on success
     * Returns: the resulting encoded string, does not signal errors
     */
    WvString strflushmem(const void *inmem, size_t inlen, bool finish = false);

protected:
    /** Sets 'okay' to false explicitly. */
    void setnotok()
        { okay = false; }

    /** Sets an error condition, then setnotok(). */
    void seterror(WvStringParm message)
        { errstr = message; setnotok(); }

    /** Sets an error condition, then setnotok(). */
    void seterror(WVSTRING_FORMAT_DECL)
        { seterror(WvString(WVSTRING_FORMAT_CALL)); }

    /** Sets 'finished' to true explicitly. */
    void setfinished()
        { finished = true; }

protected:
    /**
     * Template method implementation of isok().
     * 
     * Not called if any of the following cases are true:
     * 
     *  - okay == false
     * 
     * 
     * Most implementations do not need to override this.
     * 
     * Returns: true if the encoder is ok
     * @see setnotok
     */
    virtual bool _isok() const
        { return true; }

    /**
     * Template method implementation of isfinished().
     * 
     * Not called if any of the following cases are true:
     * 
     *  - finished == true
     * 
     * 
     * Most implementations do not need to override this.
     * 
     * Returns: true if the encoder is finished
     * @see setfinished
     */
    virtual bool _isfinished() const
        { return false; }

    /**
     * Template method implementation of geterror().
     * 
     * Not called if any of the following cases are true:
     * 
     *  - isok() == true
     *  - errstr is not null
     * 
     * 
     * Most implementations do not need to override this.
     * 
     * Returns: the error message, or the null string if _isok() == true
     * @see seterror
     */
    virtual WvString _geterror() const
        { return WvString::null; }

    /**
     * Template method implementation of encode().
     * 
     * Not called if any of the following cases are true:
     * 
     *  - okay == false
     *  - finished == true
     *  - in.used() == 0 && flush == false
     * 
     * 
     * All implementations MUST define this.
     * 
     * If you also override _isok() or _isfinished(), note that they
     * will NOT be consulted when determining whether or not to
     * invoke this function.  This allows finer control over the
     * semantics of isok() and isfinished() with respect to encode().
     * 
     * "inbuf" is the input buffer
     * "outbuf" is the output buffer
     * "flush" is if true, flushes the encoder
     * Returns: true on success
     * @see encode
     */
    virtual bool _encode(WvBuf &inbuf, WvBuf &outbuf, bool flush) = 0;

    /**
     * Template method implementation of finish().
     * 
     * Not called if any of the following cases are true:
     * 
     *  - okay == false
     *  - finished == true
     * 
     * 
     * The encoder is marked finished AFTER this function exits.
     * 
     * Many implementations do not need to override this.
     * 
     * If you also override _isok() or _isfinished(), note that they
     * will NOT be consulted when determining whether or not to
     * invoke this function.  This allows finer control over the
     * semantics of isok() and isfinished() with respect to finish().
     * 
     * "outbuf" is the output buffer
     * Returns: true on success
     * @see finish
     */
    virtual bool _finish(WvBuf &outbuf)
        { return true; }

    /**
     * Template method implementation of reset().
     * 
     * When this method is invoked, the current local state will
     * be okay == true and finished == false.  If false is returned,
     * then okay will be set to false.
     * 
     * May set a detailed error message if an error occurs.
     * 
     * Returns: true on success, false on error or if not supported
     * @see reset
     */
    virtual bool _reset()
        { return false; }
};


/** An encoder that discards all of its input. */
class WvNullEncoder : public WvEncoder
{
protected:
    virtual bool _encode(WvBuf &in, WvBuf &out, bool flush);
    virtual bool _reset(); // supported: does nothing
};


/**
 * A very efficient passthrough encoder that just merges the
 * input buffer into the output buffer.
 * 
 * Counts the number of bytes it has processed.
 * 
 * Supports reset().
 * 
 */
class WvPassthroughEncoder : public WvEncoder
{
    size_t total;
    
public:
    WvPassthroughEncoder();
    virtual ~WvPassthroughEncoder() { }

    /**
     * Returns the number of bytes processed so far.
     * Returns: the number of bytes
     */
    size_t bytes_processed() { return total; }
    
protected:
    virtual bool _encode(WvBuf &in, WvBuf &out, bool flush);
    virtual bool _reset(); // supported: resets the count to zero
};


/**
 * An encoder chain owns a list of encoders that are used in sequence
 * to transform data from a source buffer to a target buffer.
 * 
 * Supports reset() if all the encoders it contains also support
 * reset().
 * 
 */
class WvEncoderChain : public WvEncoder
{
    class ChainElem
    {
    public:
        WvEncoder *enc;
        WvDynBuf out;
        bool autofree;

        ChainElem(WvEncoder *enc, bool autofree)
	    : enc(enc), autofree(autofree) { }
        ~ChainElem() { if (autofree) delete enc; }
    };
    DeclareWvList(ChainElem);

    ChainElemList encoders;
    ChainElem *last_run;
    
public:
    /** Creates an initially empty chain of encoders. */
    WvEncoderChain();

    /** Destroys the encoder chain.  Calls zap(). */
    virtual ~WvEncoderChain();

    /**
     * Appends an encoder to the tail of the chain.
     * if "autofree" is true, takes ownership of the encoder
     */
    void append(WvEncoder *enc, bool autofree);

    /**
     * Prepends an encoder to the head of the chain.
     * if "autofree" is true, takes ownership of the encoder
     */
    void prepend(WvEncoder *enc, bool autofree);

    /**
     * Gets the autofree state of a particular encoder in the chain.
     *
     * If an encoder is in the chain multiple times, this will return
     * true if at least one instance is set to autofree.
     */
    bool get_autofree(WvEncoder *enc) const;

    /**
     * Sets the autofree state of a particular encoder in the chain.
     *
     * if "autofree" is true, takes ownership of the encoder, by ensuring
     * only one of the encoders has autofree set.  If it is false, then
     * all encoders have their autofree cleared.
     */
    void set_autofree(WvEncoder *enc, bool autofree);

    /**
     * Unlinks the encoder from the chain.
     * Deletes the encoder if it was added with autofree == true.
     */
    void unlink(WvEncoder *enc);

    /**
     * Clears the encoder chain.
     * Deletes any encoders that were added with autofree == true.
     */
    void zap();
    
    /**
     * "Continues" encoding a buffer.  Runs all data in the buffer through
     * any encoders that have been added to the chain since the last encode.
     * 
     * This is only useful once, immediately after you add one or more new
     * encoders to the chain.  However, you can call it whenever you want,
     * and if no new encoders have been added, the given data will simply
     * be (perhaps) copied unchanged into outbuf.  Note that this call
     * never does flush() or finish(), so outbuf may or may not be used.
     * 
     * The supplied inbuf is guaranteed to be empty when this function
     * returns.
     */
    bool continue_encode(WvBuf &inbuf, WvBuf &outbuf);

    /**
     * Returns true if there is data in an internal buffer.
     */
    size_t buffered();

protected:
    /**
     * Returns true if the encoder has not encountered an error.
     * 
     * WvEncoderChain is special in that it may transition from
     * isok() == false to isok() == true if the offending encoders
     * are removed from the list.
     * 
     * Returns: true iff all encoders return isok() == true
     * @see WvEncoder::_isok
     */
    virtual bool _isok() const;
    
    /**
     * Returns true if the encoder can no longer encode data.
     * 
     * WvEncoderChain is special in that it may transition from
     * isfinished() == true to isfinished() == false if the offending
     * encoders are removed from the list, but not if finish() is
     * called.
     * 
     * Returns: false iff all encoders return isfinished() == false
     */
    virtual bool _isfinished() const;

    /**
     * Returns the error message, if any.
     * 
     * WvEncoderChain is special in that it may transition from
     * !geterror() = false to !geterror() = true if the offending
     * encoders are removed from the list.
     * 
     * Returns: the first non-null error message in the chain
     */
    virtual WvString _geterror() const;
    
    /**
     * Passes the data through the entire chain of encoders.
     * Returns true iff all encoders return true.
     */
    virtual bool _encode(WvBuf &in, WvBuf &out, bool flush);
    
    /**
     * Finishes the chain of encoders.
     * 
     * Invokes finish() on the first encoder in the chain, then
     * flush() on the second encoder if new data was generated,
     * then finish() on the second encoder, and so on until all
     * encoders have been flushed and finished (assuming the first
     * encoder had already been flushed).
     * 
     * Returns true iff all encoders return true.
     */
    virtual bool _finish(WvBuf & out);

    /**
     * Resets the chain of encoders.
     * 
     * Resets all of the encoders in the chain and discards any
     * pending buffered input.  Preserves the list of encoders.
     * 
     * Returns: true iff all encoders return true.
     */
    virtual bool _reset();
    
private:
    /** Used by _encode() and _finish() */
    bool do_encode(WvBuf &in, WvBuf &out, ChainElem *start_after,
		   bool flush, bool finish);
};

#endif // __WVENCODER_H