net.rim.device.api.mime
Class MIMEInputStream

java.lang.Object
  java.io.InputStream
      net.rim.device.api.mime.MIMEInputStream

public class MIMEInputStream
extends InputStream

Input stream for reading a MIME encoded data stream.

This class implements a stream which reads in a MIME message and formats and parses the message into its constituent parts according to the MIME standard.

Sample code

 if( inputStream instanceof MIMEInputStream )
 {
   MIMEInputStream mimeStream = (MIMEInputStream) inputStream;
  
   String contentType = mimeStream.getContentType();
   if( contentType != null )
   {
     if(contentType.startsWith( BodyPart.ContentType.TYPE_MULTIPART_ALTERNATIVE_STRING ) )
     {
         // Could have also used : if(mimeStream.isMultipart())
         
         MIMEInputStream[] innerParts = mimeStream.getParts();
         for( int i = 0; i < innerParts.length; i++ )
         {
             String mimeType = innerParts[i].getContentType();
             String charset = innerParts[i].getContentTypeParameter( "charset" );
             String encoding = innerParts[i].getHeader("Content-Transfer-Encoding");
             if(encoding.equalsIgnoreCase("base64"))
             {
                 SharedInputStream sis = innerParts[i].getRawMIMEInputStream();
                 ....
             }                 
             ....
         }
     }
     else if( contentType.startsWith( BodyPart.ContentType.TYPE_APPLICATION ) )
     {
         byte[] buffer = new byte[mimeStream.available()];    
         mimeStream.read(buffer);
     }
     else if( contentType.startsWith( BodyPart.ContentType.TYPE_TEXT ) )
     {
         // ....
     }
 
     // ....
 }
 

Constructor Summary

MIMEInputStream(InputStream input)
Creates a new MIMEInputStream instance.

Method Summary
int	available() Retrieves number of available bytes.
void	close() Closes this input stream.
String	getContentDescription() Retrieves content description for this part.
String	getContentEncoding() Retrieves this part's content encoding.
String	getContentID() Retrieves this part's content ID.
String	getContentType() Retrieves this part's content type.
String	getContentTypeParameter(String attribute) Retrieves content type pararmeter by attribute.
String	getHeader(String headerFieldName) Retrieve header content for named header.
Enumeration	getHeaders() Retrieves enumeration of MIME headers.
MIMEInputStream[]	getParts() Retrieves all parts in this multi-part message.
SharedInputStream	getRawMIMEInputStream() Retrieves entire MIME part including headers.
boolean	isMultiPart() Determines if this is a multi-part message.
int	isPartComplete() Determines whether the entire contents of this MIME Part was read in or whether it was cutoff early.
int	read() Reads one byte from this stream.
int	read(byte[] buffer) Reads some bytes from this stream.
int	read(byte[] buffer, int offset, int length) Read specified number of bytes from this stream.
long	skip(long n) Skips over some bytes in this stream.

Methods inherited from class java.io.InputStream

mark, markSupported, reset

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MIMEInputStream

public MIMEInputStream(InputStream input)
                throws MIMEParsingException

Creates a new MIMEInputStream instance.

Parameters:

input - Input stream from which to read MIME encoded data.

Throws:

MIMEParsingException - If error encountered parsing input data.

Method Detail

getHeaders

public Enumeration getHeaders()

Retrieves enumeration of MIME headers. Note that the values have been converted to lower case.

Invoke this method to retrieve an enumeration of the headers found in this MIME part, including the "Content-Type", "Content-ID", etc. in addition to any extension fields. Also note that

Returns:

Headers in this MIME part.

getHeader

public String getHeader(String headerFieldName)

Retrieve header content for named header. Note that the values have been converted to lower case.

Invoke this method to retrieve the header content for a particular header. For example, given this header

  Content-Type: text/plain; boundary=111
 

invoking this method as getHeader("Content-Type") retrieves the string "text/plain; boundary=111".

Parameters:

headerFieldName - Header name for which to retrieve the content.

Returns:

Content for named header.

getRawMIMEInputStream

public SharedInputStream getRawMIMEInputStream()

Retrieves entire MIME part including headers.

Invoke this method to retrieve this entire MIME part, including headers, in a shared input stream.

Returns:

Entire MIME part.

isMultiPart

public boolean isMultiPart()

Determines if this is a multi-part message.

Returns:

True if this message contains more than one MIME part; otherwise, false.

isPartComplete

public int isPartComplete()

Determines whether the entire contents of this MIME Part was read in or whether it was cutoff early.

Returns:

A ternary value depending on the context. If the entire part is present ( which can be determined if the final boundary was read, then 1 is returned. If the part is cut-off and we can determine that, then 0 is returned. If we aren't sure, because there are no boundaries around the part, then -1 is returned.

Since:

BlackBerry API 4.0.0

getParts

public MIMEInputStream[] getParts()

Retrieves all parts in this multi-part message.

Invoke this method on a multi-part message to retrieve each contained part in a MIME input stream of its own.

Returns:

Array containing all the parts in this multi-part message; if this message is not a multi-part message, this method returns null. If this message is multi-part, but the data is cut off to early, then this will be an array of length 0.

getContentEncoding

public String getContentEncoding()

Retrieves this part's content encoding.

Returns:

Content encoding used on this part's body; if no encoding specified (or if the data is decoded internally) this method returns null.

getContentType

public String getContentType()

Retrieves this part's content type.

Returns:

Content type for this part (for example, "text/plain"); if no content type specified, then this method returns "text/plain".

getContentTypeParameter

public String getContentTypeParameter(String attribute)

Retrieves content type pararmeter by attribute.

Parameters:

attribute - Content type attribute key to look for.

Returns:

Parameter value for specified content type attribute, or null if no value found.

getContentID

public String getContentID()

Retrieves this part's content ID.

Returns:

Content ID for this part, or null if content ID not present.

getContentDescription

public String getContentDescription()

Retrieves content description for this part.

Returns:

Content description for this part, or null if content not description present.

read

public int read(byte[] buffer,
                int offset,
                int length)
         throws IOException

Read specified number of bytes from this stream.

Invoke this method to read some bytes from this stream. Note that if this stream contains a multi-part message, this method reads bytes out of the first part.

Overrides:

read in class InputStream

Parameters:

buffer - Buffer to contain data; must be large enough to contain desired number of bytes.

offset - First element in output parameter buffer at which to begin writing data; if not 0 then output parameter buffer must be at least offset + len elements long.

length - Number of bytes to read from this stream.

Returns:

Actual number of bytes read from this stream; if no more data was available when you invoked this method, it returns -1.

Throws:

IOException - If an I/O error occurs.

See Also:

InputStream.read()

read

public int read()
         throws IOException

Reads one byte from this stream.

Invoke this method read one byte from this stream. Note that if this stream contains a multi-part message, this method reads the byte out of the first part.

This method blocks until input data is available, the end of the stream is detected (and then returns -1), or an exception is thrown.

Specified by:

read in class InputStream

Returns:

Byte of data, or -1 if no more data in this stream.

Throws:

IOException - If an I/O error occurs.

read

public int read(byte[] buffer)
         throws IOException

Reads some bytes from this stream.

Invoke this method to attempt to fill a provided output parameter byte array with data from this stream. Note that if this stream contains a multi-part message, this method reads bytes out of the first part.

Overrides:

read in class InputStream

Parameters:

buffer - Buffer to contain data.

Returns:

Actual number of bytes read from this stream; if no more data was available when you invoked this method, it returns -1.

Throws:

IOException - If an I/O error occurs.

See Also:

InputStream.read(byte[], int, int)

skip

public long skip(long n)
          throws IOException

Skips over some bytes in this stream.

Invoke this method to skip the read position over a specified number of bytes in this stream, discarding the skipped bytes.

Overrides:

skip in class InputStream

Parameters:

n - Number of bytes to skip; if negative, an IllegalArgumentException is thrown by the underlying SharedInputStream.

Returns:

Actual number of bytes skipped.

Throws:

IOException - Thrown if an I/O error occurs.

available

public int available()
              throws IOException

Retrieves number of available bytes.

Invoke this method to find out the number of bytes you can freely read (or skip over) from this stream (that is, without being blocked by another invocation of one of this stream's methods, on this or another thread).

Note that if this is a multi part message, the amount available is from the first part.

Overrides:

available in class InputStream

Returns:

Number of bytes available for reading in this stream.

Throws:

IOException - If an I/O error occurs.

close

public void close()
           throws IOException

Closes this input stream.

Invoke this method to close this stream and release any system resources it uses.

Note that if this is a multi part message, then the first part is closed.

Overrides:

close in class InputStream

Throws:

IOException - If an I/O error occurs.