When writing a plugin, you usually bind a few functions to a few system
hooks, like this:

----------------------------------------------------------------------------
  $squirrelmail_plugin_hooks['attachment text/html']['attachment_common'] = 
      'attachment_common_link_html';
----------------------------------------------------------------------------

This process is quite painless, right?  Well, tying into attachment_common
is that easy too.

If you want your plugin to handle special attachments, you just hook into a
few functions and all will be set.  For the purpose of this example, we
shall use the MIME type of 'application/x-zip' and file extension of '.zip' 
for your plugin.

The first thing you should do is hook into the appropriate hooks

----------------------------------------------------------------------------
$squirrelmail_plugin_hooks['attachment application/x-zip']['your_plugin'] =
   'your_plugin_application_zip_handler';
$squirrelmail_plugin_hooks['attachment_common-load_mime_types']['your_plugin']
   = 'your_plugin_load_mime_types';
----------------------------------------------------------------------------

(Sorry about the long names and all.)

Then you need to write your functions that handle these hooks.  We'll start
with the load_mime_types one, since it is the easiest.

load_mime_types is actually called by the attachment_common plugin.  No data
is sent, nor is any data used that is returned.  The purpose of this hook is
to register file extensions with mime types for auto-detections.  This hook
is only called if a file is "application/octet-stream" (which basically
means "I don't know" for the type of attachment) and we use our
auto-detection code.  The process is painless.

----------------------------------------------------------------------------
function your_plugin_load_mime_types() {
   global $FileExtensionToMimeType;
   
   $FileExtensionToMimeType['zip'] = 'application/x-zip';
}
----------------------------------------------------------------------------

See?  I told you it was simple.  This says that for any
"application/octet-stream" file that we encounter which happens to have a
.zip extension, we should treat it as an application/x-zip file.  Note that
you do not add the '.' before 'zip' for a .zip extension.  Also, note that
the 'application/x-zip' and the file extension both should not contain
uppercase.  It is translated to lowercase elsewhere in SquirrelMail and to
make sure that other plugins can hook into this properly, we should keep it 
lowercase.

Now we need to write the function that handles attachments.  This one is a
lot more tricky.  I have inserted comments in the code.

----------------------------------------------------------------------------
function your_plugin_application_zip_handler(&$Args)
{
  // Args = incoming and outgoing information
  //
  // $Args[1] = the array of actions
  //
  // Use the plugin name for adding an action
  // $Args[1]['your_plugin'] = array for href and text
  //
  // $Args[1]['attachment_common']['text'] = What is displayed
  // $Args[1]['attachment_common']['href'] = Where it links to
  //
  // This sets the 'href' of this plugin for a new link.  It also forces the
  // file type to be downloaded as "application/x-zip" just in case the file
  // was originally "application/octet-stream" and was auto-detected by file
  // extension.  This link is to the download page.  It requires tons of info
  // in order to download the right message part in the right message in the
  // right folder.
  //
  // Really, we should be doing more than just downloading the file, but for
  // the ease of this example, I am just going to link to the download page.
  // Some typical things you can do with a .zip file is to scan it for
  // viruses, test it to make sure it isn't corrupted, and browse the
  // archive in your web browser with the ability to download individual
  // files without needing a zip program on your end.
  //
  // Remember, you'll need to code any extra functionality yourself.
  
  $Args[1]['your_plugin']['href'] = '../src/download.php?startMessage=' .
     $Args[2] . '&passed_id=' . $Args[3] . '&mailbox=' . $Args[4] . 
     '&passed_ent_id=' . $Args[5] . 
     '&override_type0=application&override_type1=z-xip';
     
  // Ok.  There's a lot of info there.
  // $Args[2] = the starting message for the message list (to go back)
  // $Args[3] = the message ID
  // $Args[4] = the mailbox name
  // $Args[5] = The entity ID for the attachment in the mail message
  //
  // If we got here from a search, we should preserve these variables
  
  if ($Args[8] && $Args[9])
     $Args[1]['your_plugin']['href'] .= '&where=' . 
     urlencode($Args[8]) . '&what=' . urlencode($Args[9]);
  
  // $Args[8] = where we are searching
  // $Args[9] = what we were searching for
  //
  // The link that we created needs a name.  Really, we should be doing more
  // than just downloading this file (that's what the download link is for!),
  // but we are not.  I guess we should call this link "download".

  $Args[1]['your_plugin']['text'] = _("download");
  
  // Each attachment has a filename on the left, which is a link.
  // Where that link points to can be changed.  Just in case the link above
  // for viewing text attachments is not the same as the default link for
  // this file, we'll change it.
  //
  // This is a lot better in the image links, since the defaultLink will just
  // download the image, but the one that we set it to will format the page
  // to have an image tag in the center (looking a lot like this text viewer)
  
  $Args[6] = $Args[1]['your_plugin']['href'];
  
  // $Args[6] = The URL for where we should go if we click on the filename
  //            from the message window (instead of clicking on a link that
  //            says 'download' or 'view'
  // $Args[7] = the filename (if you would need that)
}
----------------------------------------------------------------------------

I think that basically sums it up.  Make sure to check out how the
attachment_common plugin handles images (note the link it creates and the
image.php file).

Hope this helps!
