1\function{_base64_decoder_accumulate}
2\synopsis{Accumulate data to be base64 decoded}
3\usage{_base64_decoder_accumulate(Base64_Type b64, String_Type data)}
4\description
5  This routine adds a tring to the base64 decoder queue of the
6  specifed Base64_Type object, previously instantiated using the
7  \ifun{_base64_decoder_new}.
8
9  See the documentation for \ifun{_base64_decoder_new} for more
10  detailed usage.
11\seealso{_base64_decoder_new, _base64_decoder_close, _base64_encoder_new}
12\done
13
14\function{_base64_decoder_new}
15\synopsis{Intantiate a new base64 decoder}
16\usage{Base64_Type _base64_decoder_new (Ref_Type func [,func_data])}
17\description
18  This routine returns instantiates a Base64_Type decoder object that
19  may be used to decode base64 data.  It require a single
20  \exmp{Ref_Type} parameter that is a reference to a callback function
21  that the decoder will call with with (partially) decoded data.  The second
22  argument, \exmp{func_data}, is optional.  If present it will also be
23  passed to the callback function.
24
25  The callback function must be defined to accept one or two
26  parameters, depending upon whether the \ifun{_base64_decoder_new} function
27  was called with the optional \exmp{func_data} argument.  If
28  \exmp{func_data} was passed, then it will be passed as the first
29  argument to the callback function.  The (partially) encoded string
30  is passed as the last argument.  The callback function shall return
31  nothing.
32\example
33  The following example defines a function that base64-decodes a string.
34#v+
35   private define decode_callback (strp, decoded_str)
36   {
37     @strp = @strp + decoded_str;
38   }
39
40   define b64decode_string (str)
41   {
42     variable b = ""B;     % The decoded string is binary
43     variable b64 = _base64_decoder_new (&decode_callback, &b);
44     _base64_decoder_accumulate (b64, str);
45     _base64_decoder_close (b64);
46     return b;
47   }
48#v-
49\example
50  The following example takes data from an input file pointer
51  \exmp{fpin} and writes the decoded data to an output file pointer
52  \exmp{fpout}:
53#v+
54   private define decoder_callback (fpout, data)
55   {
56      () = fwrite (data, fpout);
57   }
58
59   define base64_decode_file (fpin, fpout)
60   {
61      variable b64 = _base64_decoder_new (&encoder_callback, fpout);
62      variable line;
63      while (-1 != fgets (&line, fpin))
64        _base64_decoder_accumulate (b64, line);
65      _base64_decoder_close (b64);
66   }
67#v-
68\seealso{_base64_decoder_accumulate, _base64_decoder_close, _base64_encoder_new}
69\done
70
71\function{_base64_decoder_close}
72\synopsis{Flush and delete a base64 decoder}
73\usage{_base64_decoder_close (Base64_Type b64)}
74\description
75  This function must be called when there is no more data for the
76  specified base64 decoder to process.  See the documentation for
77  \ifun{_base64_decoder_new} for additional information and usage.
78\seealso{_base64_decoder_new, _base64_decoder_accumulate, _base64_encoder_close}
79\done
80
81\function{_base64_encoder_accumulate}
82\synopsis{Accumulate data to be base64 encoded}
83\usage{_base64_encoder_accumulate(Base64_Type b64, BString_Type data)}
84\description
85  This routine adds a binary string to the encoder queue of the
86  specifed Base64_Type object, previously instantiated using the
87  \ifun{_base64_encoder_new}.
88
89  See the documentation for \ifun{_base64_encoder_new} for more
90  detailed usage.
91\seealso{_base64_encoder_new, _base64_encoder_close, _base64_decoder_new}
92\done
93
94\function{_base64_encoder_new}
95\synopsis{Intantiate a new base64 encoder}
96\usage{Base64_Type _base64_encoder_new (Ref_Type func [,func_data])}
97\description
98  This routine returns instantiates a Base64_Type decoder object that
99  may be used to base64-encode data.  It require a single
100  \exmp{Ref_Type} parameter that is a reference to a callback function
101  that the encoder will call with the data to be encoded.  The second
102  argument, \exmp{func_data}, is optional.  If present it will also be
103  passed to the callback function.
104
105  The callback function must be defined to accept one or two
106  parameters, depending upon whether the \ifun{_base64_encoder_new} function
107  was called with the optional \exmp{func_data} argument.  If
108  \exmp{func_data} was passed, then it will be passed as the first
109  argument to the callback function.  The (partially) encoded string
110  is passed as the last argument.  The callback function shall return
111  nothing.
112\example
113  The following example defines a function that base64 encodes a string.
114#v+
115   private define encode_callback (strp, encoded_str)
116   {
117     @strp = @strp + encoded_str;
118   }
119
120   define b64encode_string (bstr)
121   {
122     variable s = "";
123     variable b64 = _base64_encoder_new (&encode_callback, &s);
124     _base64_encoder_accumulate (b64, bstr);
125     _base64_encoder_close (b64);
126     return b;
127   }
128#v-
129\example
130  The following example takes data from an input file pointer
131  \exmp{fpin} and writes the encoded data to an output file pointer
132  \exmp{fpout}:
133#v+
134   private define encoder_callback (fpout, encoded_data)
135   {
136      () = fputs (encoded_data, fpout);
137   }
138
139   define define base64_encode_file (fpin, fpout)
140   {
141      variable b64 = _base64_encoder_new (&encoder_callback, fpout);
142      variable bytes;
143      while (-1 != fread_bytes (&bytes, 512, fpin))
144        _base64_encoder_accumulate (b64, bytes);
145      _base64_encoder_close (b64);
146   }
147#v-
148\seealso{_base64_encoder_accumulate, _base64_encoder_close, _base64_decoder_new}
149\done
150
151\function{_base64_encoder_close}
152\synopsis{Flush and delete a base64 encoder}
153\usage{_base64_encoder_close (Base64_Type b64)}
154\description
155  This function must be called when there is no more data for the
156  specified base64 encoder to process.  See the documentation for
157  \ifun{_base64_encoder_new} for additional information and usage.
158\seealso{_base64_encoder_new, _base64_encoder_accumulate, _base64_decoder_close}
159\done
160
161