next up previous
Next: The Trivial Decoder Up: The UUDeview Decoding Library Previous: Decoding Functions

Encoding Functions

There are a couple of functions to encode data into a file. You will usually need no more than one of them, depending on the job you want to do. The functions also differ in the headers they generate. Some functions do generate full MIME-compliant headers. This may sound like the best choice, but it's not always the wisest choice. Please follow the following guidelines.

All of the functions have a bunch of parameters for greater flexibility. Don't be confused by their number, usually you'll need to fill only a few of them. There's a number of common parameters which can be explained separately:

FILE *outfile

The output stream, where the encoded data is written to.
FILE *infile, char *infname

Where the input data shall be read from. Only one of both values must be specified, the other can be NULL.
char *outfname

The name by which the recipient will receive the file. It is used on the ``begin'' line for uuencoded and xxencoded data, and in the headers of MIME-formatted messages. If this parameter is NULL, it defaults to infname. It must be specified if data is read from a stream and infname==NULL.
int filemode

For uuencoded and xxencoded data, the file permissions are encoded into the ``begin'' line. This mode can be specified here. If the value is 0, it will be determined by performing a stat() call on the input file. If this call should fail, a value of 0644 is used as default.
int encoding

The encoding to use. One of the three constants UU-_ENCODED, XX-_ENCODED or B64ENCODED.

Now for the functions ...

int UUEncodeMulti (FILE *outfile, FILE *infile,
   char *infname, int encoding,
   char *outfname, char *mimetype,
   int filemode)

Encodes data into a subpart of a MIME ``multipart'' message. Appropriate ``Content-Type'' headers are produced, followed by the encoded data. The application must provide the envelope and boundary lines. If mimetype!=NULL, it is used as value for the ``Content-Type'' field, otherwise, the extension from outfname or infname (if outfname==NULL) is used to look up the relevant type name.

int UUEncodePartial (FILE *outfile, FILE *infile,
   char *infname, int encoding,
   char *outfname, char *mimetype,
   int filemode, int partno,
   long linperfile)

Encodes data as the body of a MIME ``message/partial'' message. This type allows message fragmentation. This function must be called repetitively until it runs out of input data. The application must provide a valid envelope with a ``message/partial'' content type and proper information about the part numbers.

Each call produces linperfile lines of encoded output. For uuencoded and xxencoded files, each output line encodes 45 bytes of input data, each Base64 line encodes 57 bytes. If linperfile==0, this function is equivalent to UUEncodeMulti.

Different handling is necessary when reading from an input stream (if infile!=NULL) compared to reading from a file (if infname!=NULL). In the first case, the function must be called until feof() becomes true on the input file, or an error occurs. In the second case, the file will be opened internally. Instead of UURET-_OK, a value of UURET-_CONT is returned for all but the last part.

int UUEncodeToStream (FILE *outfile, FILE *infile,
   char *infname, int encoding,
   char *outfname, int filemode)

Encodes the input data and sends the plain output without any headers to the output stream. Be aware that for Base64, the output does not include any information about the filename.

int UUEncodeToFile (FILE *infile, char *infname,
   int encoding, char *outfname,
   char *diskname, long linperfile)

Encodes the input data and writes the output into one or more output files on the local disk. No headers are generated. If diskname==NULL, the names of the encoded files are generated by concatenating the save path (see the UUOPT-_SAVEPATH option) and the base name of outfname or infname (if outfname==NULL).

If diskname!=NULL and does not contain directory information, the target filename is the concatenation of the save path and diskname. If diskname is an absolute path name, it is used itself.

From the so-generated target filename, the extension is stripped. For single-part output files, the extension set with the UUOPT-_ENCEXT option is used. Otherwise, the three-digit part number is used as extension. If the destination file does already exist, the value of the UUOPT-_OVERWRITE is checked; if overwriting is not allowed, encoding fails with UURET-_EXISTS.

int UUE_PrepSingle (FILE *outfile, FILE *infile,
   char *infname, int encoding,
   char *outfname, int filemode,
   char *destination, char *from,
   char *subject, int isemail)

Produces a complete MIME-formatted message including all necessary headers. The output from this function is usually fed directly into a mail delivery agent which honors headers (like ``sendmail'' or ``inews'').

If from!=NULL, it is sent as the sender's email address in the ``From'' header field. Some MDA programs are able to provide the sender's address themselves, so this value may be NULL in certain cases.

If subject!=NULL, the text is included in the ``Subject'' header field. The subject is extended with information about the file name and part number (in this case, always ``(001/001)'').

``Destination'' must not be NULL. Depending on the ``isemail'' flag, its contents are sent either in the ``To'' or ``Newsgroups'' header field.

int UUE_PrepPartial (FILE *outfile, FILE *infile,
   char *infname, int encoding,
   char *outfname, int filemode,
   int partno, long linperfile,
   long filesize,
   char *destination, char *from,
   char *subject, int isemail)

Similar to UUE_PrepSingle, but produces a complete MIME-formatted ``message/partial'' message including all necessary headers. The function must be called repetitively until it runs out of input data. For more explanations, see the description of the function UUEncodePartial above.

The only additional parameter is filesize. Usually, this value can be 0, as the size of the input file can usually be determined by performing a stat() call. However, this might not be possible if infile refers to a pipe. In that case, the value of filesize is used.

If the size of the input data cannot be determined, and filesize is 0, the function refuses encoding into multiple files and produces only a single stream of output.

If data is read from a file instead from a stream (infile==NULL), the function opens the file internally and returns UURET-_CONT instead of UURET-_OK on successful completion for all but the last part.


next up previous
Next: The Trivial Decoder Up: The UUDeview Decoding Library Previous: Decoding Functions
build daemon 2002-04-15