PHP Att Codec

By Stéphane Degré and Renaud Hager in March 2004

Introduction :

PHP att_codec is a module (or an extension) for PHP4 written in C language.
It is the PHP version of the C-library UUDeview (http://www.fpx.de/fp/Software/UUDeview/).
Indeed, this extension provides a lot of functions that are able to code/decode large mails attachments.
These functions support the following formats : Base64, UUEncoding, XXEncoding and Yenc.

Requirements :

Windows requirements :

If you don't want to compile the extension, directly go to the section "Installation without compilation".
If you want to compile the extension, a compliable and working version of PHP4 is required. Moreover, this extension requires the C-uudeview library to be installed. Grab the latest version for Windows from http://www.miken.com/uud/developer/source.htm#dll. Unzip the sources on your local disk C. You have now two new directories : "Vc" and "VC16". Go to "Vc\uudeview" and open the workspace "uudeview.dsw" with Microsoft Visual C++. Open up Project > Settings. On the C/C++ tab, Code Generation Category, change Use run-time Library to "Multithreaded DLL". Then build the project. Copy the resulting file "Release\uudeview.dll" to your "C:\Windows" directory. Note that the "uudeview.lib" file was also created.

Unix requirements :

You have to compile the extension, that's why a compliable version of PHP4 is required. Moreover, this extension requires the C-uudeview library to be installed. Grab the latest version for UNIX from http://www.fpx.de/fp/Software/UUDeview/ and compile it (See the documentation of UUDeview for more details).
We are now on the last step of the requirements :
Go to the "uudeviewxxx/uulib" directory and copy the "config.h", "uudeview.h" and "crc32.h" files into "/usr/local/include/". Additionally when you compiled UUDeview, a file named libuu.a was created. Also put this in the "/usr/local/lib/" directory.
This last step is optionnal, it can be replaced by indicating the installation path of UUDeview when you compile the extension (see below).

Installation :

On Windows systems :

With compilation :

Download the module sources here.
Unzip the sources in the "ext" directory of your compliable version of PHP. Open the Workspace "att_codec\att_codec.dsw" with Microsoft Visual C++.
Open up "Project > Settings". On the "C/C++" tab, in the "Preprocessor" Category, look at "Additional include directories" and replace "D:\Projet 50H\UUDeview\sources\VC16\UUD16" by “C:\VC16\UUD16” or your corresponding directory containing the following files : “crc32.h”, “config.h” and “uudeview.h”.
On the Link tab, in the General Category, look at "Output filename" and change "C:\php\extensions\" by your php extensions directory. Let “php_att_codec.dll” for the module filename.
In the Input Category, look at “Additional library path” :
- Change “C:\php” by your corresponding directory containing the file "php4ts.lib",
- Change "D:\Projet 50H\UUDeview\sources\Vc\uudeview\Release" by “C:\Vc\uudeview\Release” or your corresponding directory containing the file "uudeview.lib".
You can now build the project.

Without compilation :

Download the binaries here.
Unzip them and then copy the "php_att_codec.dll" file to your php extensions directory (In general, it is “C:\php\extensions\”).
Then copy the "uudeview.dll" file to your "C:\Windows" directory.

For both :

In the php.ini file (C:\Windows\php.ini) :

Specify the extensions directory (for example : extension_dir = C:\php\extensions).
Add a line for the new extension (extension=php_att_codec.dll) under the declaration of the other extensions.

On UNIX systems :

Download the module sources here.
Unzip the sources in the "ext" directory of your compliable version of PHP.
Then go to the directory of your compliable version of PHP and execute the command "./buildconf --force".
You have now to configure php :
- "./configure --with-att_codec" if you have done the optionnal step of the requirements.
- "./configure --with-att_codec=uudeview_path" if you haven't done the optionnal step of the requirements. Replace "uudeview_path" by the absolute path where the uudeview library is installed.
- Don't forget your others configure arguments (for example "--with-apache")
Finally execute the following commands : "make" and "make install".
You can now recompile apache and then the extension will be available.

Resource Types, Object Types and Predefined Constants

The resources, objects and constants below are defined by this extension, and will only be available when the extension has been dynamically loaded at runtime.

Predefined Constants for Message CallBack

UUMSG_MESSAGE (integer)
UUMSG_NOTE (integer)
UUMSG_WARNING (integer)
UUMSG_ERROR (integer)
UUMSG_FATAL (integer)
UUMSG_PANIC (integer)

Predefined Object for Busy CallBack

This extension defines an object corresponding to the C structure uuprogress. This object has the following members :

action (integer)
curfile (string)
partno (integer)
numparts (integer)
percent (integer)
fsize (integer)

Predefined Constants for Busy CallBack

UUACT_IDLE (integer)
UUACT_SCANNING (integer)
UUACT_DECODING (integer)
UUACT_COPYING (integer)
UUACT_ENCODING (integer)

Predefined Resource and Object for File List

This extension defines an object and a resource corresponding to the C structure uulist. The object has the following members :

state (integer)
mode (integer)
uudet (integer)
size (integer)
filename (string)
subfname (string)
mimetype (string)
binfile (string)
haveparts (array)
misparts (array)

Predefined Constants for File List

UUFILE_MISPART (integer)
UUFILE_NOBEGIN (integer)
UUFILE_NOEND (integer)
UUFILE_NODATA (integer)
UUFILE_OK (integer)
UUFILE_ERROR (integer)
UUFILE_DECODED (integer)
UUFILE_TMPFILE (integer)
UU_ENCODED (integer)
B64ENCODED (integer)
XX_ENCODED (integer)
BH_ENCODED (integer)
PT_ENCODED (integer)
QT_ENCODED (integer)
YENC_ENCODED (integer)

Predefined Constants for Return Values

UURET_OK (integer)
UURET_IOERR (integer)
UURET_NOMEM (integer)
UURET_ILLVAL (integer)
UURET_NODATA (integer)
UURET_NOEND (integer)
UURET_UNSUP (integer)
UURET_EXISTS (integer)
UURET_CONT (integer)
UURET_CANCEL (integer)

Predefined Constants for Options

UUOPT_VERSION (integer)
UUOPT_FAST (integer)
UUOPT_DUMBNESS (integer)
UUOPT_BRACKPOL (integer)
UUOPT_VERBOSE (integer)
UUOPT_DESPERATE (integer)
UUOPT_IGNREPLY (integer)
UUOPT_OVERWRITE (integer)
UUOPT_SAVEPATH (integer)
UUOPT_IGNMODE (integer)
UUOPT_DEBUG (integer)
UUOPT_ERRNO (integer)
UUOPT_PROGRESS (integer)
UUOPT_USETEXT (integer)
UUOPT_PREAMB (integer)
UUOPT_TINYB64 (integer)
UUOPT_ENCEXT (integer)
UUOPT_REMOVE (integer)
UUOPT_MOREMIME (integer)

General functions :

php_uuinitialize -- Initializes the library.
php_uucleanup -- Cleans up all resources that have been allocated.
php_uugetoption -- Returns the value of an option.
php_uusetoption -- Sets a value to an option.
php_uustrerror -- Returns a string representation of an error code.
php_uusetmsgcallback -- Sets the Message Callback function.
php_uusetbusycallback -- Sets the Busy Callback function.
php_uusetfnamefilter -- Sets the Filename Filter function.
php_uufnamefilter -- Returns the string returned by the Filename Filter.

Decoding functions :

php_uuloadfile -- Scans a file for encoded data and inserts the result into the file list.
php_uugetfilelistitem -- Returns a uulist resource from the file list.
php_uulistitemtoobject -- Converts a uulist resource into an object.
php_uurenamefile -- Renames one item of the file list.
php_uudecodetotemp -- Decodes a uulist resource into a temporary file.
php_uuremovetemp -- Erases a temporary file.
php_uudecodefile -- Decodes a file and copies it to its final location.
php_quick_uudecode -- Decodes all the multi-parts or single-part files given.
php_uuinfofile -- Calls a user function with one information line of a file.
php_uusmerge -- Attempts a "Smart Merge" of parts that seem to belong to different files but which could belong to the same.

Encoding functions -- Common parameters for the encoding functions :

php_uuencodemulti -- Encodes data into a subpart of a MIME-"multipart" message.
php_uuencodepartial -- Encodes data as the body of a MIME-"message/partial" message.
php_uuencodetostream -- Encodes the input data and sends the plain output without any headers to the output stream.
php_uuencodetofile -- Encodes the input data and writes the output into one or more output files on the local disk.
php_quick_uuencode -- Encodes the input data and writes the output into one or more output files on the local disk.
php_uue_prepsingle -- Produces a complete MIME-formatted message including all necessary headers.
php_uue_preppartial -- Produces a complete MIME-formatted "message/partial" message including all necessary headers.

Examples

Example 1 : A full decoding example with the standard functions.
Example 2 : The same full decoding example with the special function php_quick_uu_decode.
Example 3 : A full encoding example with the standard functions.
Example 4 : The same full encoding example with the special function php_quick_uu_encode.
Example 5 : A full encoding example where the files are opened in the php script.
Example 6 : A full encoding example where one input file is encoded in multiple output files.