Copyright: Copyright ® 1996 Progress Software Corporation


 Getting Started with the CIMIME Control

Related Topics

This topic introduces Multipurpose Internet Mail Extensions (MIME) and their implementation with the Crescent Internet ToolPak MIME Control (CIMIME). You can access the following topics:

What MIME is

What the CIMIME control is

How to use the CIMIME control

The last topic, How to use the CIMIME control, identify tasks that CIMIME supports; it lists the properties to set and the methods to call, then it illustrates the task with a code sample.


 What is MIME?

Related Topics

MIME is a standard that specifies the format of Internet message bodies. It defines how you can include multiple objects (of different types) in a single message. The different types of objects that you can include in a message include: images, audio, and other material that might be in a character set that is not US-ASCII. The standard supports the exchange of messages so that no data is lost during the message exchange.


 What is the CIMIME Control?

Related Topics

The Crescent Internet ToolPak MIME (CIMIME) control lets Visual Basic programmers build applications that can encode and decode files or mail attachements. It complies with the MIME standards defined in RFC1521 and RFC1522.

The CIMIME control can encode or decode files or mail attachments in stand-alone mode or when combined with the CISMTP or CIPOP controls. When used with the CISMTP control, the encoded text is fed to the CISMTP.Message property just as any message would be sent. When used with the CIPOP control, the encoded text is fed to the CIMIME control via the CIPOP.Message property. If you use CIMIME to encode, the source is a non-text file. If you use CIMIME to decode, the source is a mail message.

CIMIME has a simple programming interface in which you set property values and call methods to perform the desired tasks. The methods (which generally do not take arguments) take the necessary data directly from the property sheet. When the method completes, the control updates properties and fires events as necessary. The control, by default will fire the ongoing status of the encoding or decoding process. Note that this enhanced status firing does negatively affect performance.


 Programming Tasks

Related Topics

The following topics describe how to program some common tasks with the CIMIME control.

How to encode a file

How to decode a file

Each topic lists the properties that you must set, and the methods that you must call to perform a specific task, and identifies the events that are fired. A code fragment that illustrates the task follows the task list.


Encoding a file using CIMIME
 Encoding a File

Related Topics

CIMIME can encode data whose source is a file, and it can deliver the encoded data as a stream.. This task describes how CIMIME reads a file, encodes the data, and writes the encoded data to a file.

Follow these steps to encode data using CIMIME:

1. Set these properties:
SourceFileName
DestinationFileName

2. Call the MIMEEncode method.

3. When the data is encoded, the EncodingFinished event fires.

Heres what the code looks like:

Form_Load
CIMIME1.SourceFileName = C:\Windows\CarvedStone.bmp
CIMIME1.DestinationFileName = C:\temp\cs.bmp
CIMIME1.MIMEEncode

CIMIME_EncodingFinished()

The encoded data is available in the DestinationFileName.

Note that if you do not supply a SourceFileName or a DestinationFileName, CIMIME displays a dialog that prompts you for this information.


Decoding a file using MIME
 Decoding a File

Related Topics

CIMIME can decode data whose source is a file or a data stream, and it can deliver the decoded data as a stream or in a file. This task describes how CIMIME reads a file, decodes the data, and writes the decoded data to a file.

Follow these steps to decode a file encoded using MIME.

1.	Set these properties:
SourceFileName
DestinationFileName

2. Call the MIMEDecode method.

3. The data is decoded when the DecodingFinished event fires.

Heres what the code looks like:

Form_Load

CIMIME1.SourceFileName = C:\temp\cs.bmp
.	CIMIME1.DestinationFileName = C:\Windows\CarvedStone.bmp
.	CIMIME1.MIMEDecode

CIMIME_DecodingFinished()

The decoded data is available in the file identified by the DestinationFileName property.

Note that if you do not supply a SourceFileName or a DestinationFileName, CIMIME displays a dialog that prompts you for this information.


Getting Started with the CIMIME Control
What is MIME?
What is the CIMIME Control?
Programming Tasks
How to encode a file
How to decode a file


What is MIME?
What is the CIMIME Control?
Programming Tasks
How to encode a file
How to decode a file
The Crescent Internet ToolPak MIME Control Reference


Getting Started with the CIMIME Control
What is the CIMIME Control?
Programming Tasks
How to encode a file
How to decode a file
The Crescent Internet ToolPak MIME Control Reference


Getting Started with the CIMIME Control
What is MIME?
Programming Tasks
How to encode a file
How to decode a file
The Crescent Internet ToolPak MIME Control Reference


Getting Started with the CIMIME Control
What is MIME?
What is the CIMIME Control?
How to encode a file
How to decode a file
The Crescent Internet ToolPak MIME Control Reference


Getting Started with the CIMIME Control
What is MIME?
What is the CIMIME Control?
Programming Tasks
How to decode a file
The Crescent Internet ToolPak MIME Control Reference


Getting Started with the CIMIME Control
What is MIME?
What is the CIMIME Control?
Programming Tasks
How to encode a file
The Crescent Internet ToolPak MIME Control Reference


 The Crescent Internet ToolPak MIME Control

Related Topics

Control File

CIMIME.OCX

Object Type

CIMIME

Purpose

The Crescent Internet ToolPak MIME control can be used to provide MIME Encode/Decode capability to mail. The decoded data can be sent to the Crescent CISMTP control. In addition, the data can originate from the Crescent CIPOP control.

The Crescent Internet ToolPak CIMIME control can be used to:

Encode files (to 7-bit ASCII standard) that you intend to mail.

Unencode files that have been encoded using the MIME standard.

The CIMIME control complies with the MIME standard defined in RFCs 1521 and 1522.

Properties

AboutBox	Container	ContentType c
DestinationFileName c	DestinationFileSize c	DragIcon
DragMode	FireStatus c	Height
Index	Left	Name
Object	Parent	ShowWhatsThis
SourceFileName c	SourceFileSize c	Tag
Top	Visible	WhatsThisHelpID
Width


Events

Decoded c	DecodingFinished c	DecodingStarted c
DragDrop	DragOver	Encoded c
EncodingFinished c	EncodingStarted c
Methods

MIMEDecode c	MIMEEncode c
c A custom or modified property, method, or event.


 ContentType Property

Applies To

CIMIME

Purpose

The ContentType property returns an educated guess of the content type based on the encoded data. If you are encoding data, you must supply this information. The default is application/octet-stream.

Syntax

[string$] = [Form.] CIMIME.ContentType

Data Type

String

Usage

Read/Write at runtime.

Comments

During a decode operation the CIMIME control attempts to obtain information about the file from the data. The information comes from the message header (ie. bmp or Image, etc.)

The CIMIME control updates the ContentType property when the DecodingStarted event fires.

See Also

DecodingStarted, SourceFileName


 DestinationFileName Property

Applies To

CIMIME

Purpose

The DestinationFileName property sets or returns the fully qualified pathname of the file where the encoded or decoded data will reside.

Syntax

[Form.]CIMIME.DestinationFileName[ = string$]

Data Type

String

Usage

Read/Write at design time and runtime.

Comments

You must set the DestinationFileName property before calling the MimeDecode or MimeEncode methods. If you do not set the DestinationFileName property, CIMIME displays a dialog that prompts you for this information.

See Also

DecodingFinished, EncodingFinished, MIMEDecode, MIMEEncode


 DestinationFileSize Property

Applies To

CIMIME

Purpose

The DestinationFileSize property returns the size (in bytes) of the file (DestinationFileName property) where the encoded or decoded data finally resides.

Syntax

[Form.]CIMIME.DestinationFileSize[ = long&]

Data Type

Long

Usage

Read only at runtime.

Comments

The DestinationFileSize property is updated once the encoding or decoding process completes.

See Also

DecodingFinished, DestinationFileName, EncodingFinished, MIMEDecode, MIMEEncode


 FireStatus Property

Applies To

CIMIME

Purpose

The FireStatus property determines whether the Encoded or Decoded events fire as a file is being encoded or decoded.

Syntax

[Form.]CIMIME.FireStatus[ = boolean]

Data Type

Boolean

Usage

Read/Write at design time and runtime.

Comments

The FireStatus property lets you determine whether you want status information to be available to a Visual Basic application. When set to True, the Encoded and Decoded events fire as a file is being encoded or decoded. When set to False, the Encoded and Decoded events fire after the decode or encode process is complete. Setting this property to True can cause the encode or decode operation to take longer because of the overhead associated with firing the Encoded and Decoded events.

See Also

Decoded, Encoded


 SourceFileName Property

Applies To

CIMIME

Purpose

The SourceFileName property sets or returns the fully qualified pathname of the file where the data to be encoded or decoded originates

Syntax

[Form.]CIMIME.SourceFileName[ = string$]

Data Type

String

Usage

Read/Write at design time and runtime.

Comments

You must set the SourceFileName property before calling the MIMEDecode or MIMEEncode methods. If you do not set the SourceFileName property, CIMIME displays a dialog box that prompts you for the name.

See Also

DecodingFinished, DestinationFileName, EncodingFinished, MIMEDecode, MIMEEncode


 SourceFileSize Property

Applies To

CIMIME

Purpose

The SourceFileSize property returns the size (in bytes) of the source file where the encoded or decoded data originates

Syntax

[long&] = [Form.] CIMIME.SourceFileSize

Data Type

Long

Usage

Read only at runtime.

Comments

The size is available once the CIMIME control has opened the file to read either encoded or decoded data from it.

See Also

DecodingFinished, DestinationFileName, EncodingFinished, MIMEDecode, MIMEEncode, SourceFileName


 Decoded Event

Applies To

CIMIME

Purpose

The Decoded event gives the Visual Basic application statistics about the current decoding operation. It fires each time the control has encoded a line and written the encoded line to the destination file.

Syntax

CIMIME_Decoded(BytesRead as Long, BytesWritten as Long, LinesDecoded as Long)

Comments

This event is useful in determining the status of a decode operation. The FireStatus property must be set to True for this event to fire. You can determine how much data has been processed by checking the value of BytesRead&, BytesWritten&, and LinesDecoded&.

When the data has been completely processed, the DecodingFinished event fires.

See Also

DecodingFinished, DecodingStarted, MIMEDecode


 DecodingFinished Event

Applies To

CIMIME

Purpose

The DecodingFinished event notifies the Visual Basic application that the decoding operation has finished and that the DestinationFileSize property can now be read.

Syntax

Sub CIMIME1_DecodingFinished()

Comments

The DecodingFinished event fires when the control closes the source and destination files.

You initiate a decode operation by calling the MIMEDecode method which fires the DecodingStarted event. If you set the FireStatus property to True, you can gather data about the progress of the decode operation through the Decoded event.

See Also

DecodingStarted, SourceFileName


 DecodingStarted Event

Applies To

CIMIME

Purpose

The DecodingStarted event notifies the Visual Basic application that the decoding operation has started and that the SourceFileSize property can now be read.

Syntax

Sub CIMIME1_DecodingStarted()

Comments

The DecodingStarted event fires when the control has opened the source (SourceFileName property) and destination files (DestinationFileName property) and the decoding operation has started.

You initiate a decode operation by calling the MIMEDecode method. When all of the data is decoded, the DecodingFinished event fires. If you set the FireStatus property to True, you can gather data about the progress of the decode operation through the Decoded event.

See Also

Decoded, DecodingFinished, DestinationFileName, DestinationFileSize, MIMEDecode, SourceFileName


 Encoded Event

Applies To

CIMIME

Purpose

The Encoded event provides statistics about the current encoding operation to the Visual Basic application. It fires each time the control has encoded a line and written the encoded line to the destination file.

Syntax

Sub CIMIME1_Encoded(BytesRead as Long, BytesWritten as Long, LinesEncoded as Long)

Comments

You initiate an encode operation by calling the MIMEEncode method. Once the encode operation starts, the EncodingStarted event fires.

This event is useful in determining the status of an encode operation. You can determine how much data has been processed by checking the values of BytesRead&, BytesWritten&, and LinesEncoded&.

See Also

EncodingFinished, EncodingStarted, MIMEEncode


 EncodingFinished Event

Applies To

CIMIME

Purpose

The EncodingFinished event notifies the Visual Basic application that the encoding operation has finished and that the DestinationFileSize property can now be read.

Syntax

Sub CIMIME1_EncodingFinished()

Comments

The EncodingFinished event fires when CIMIME closes the source (SourceFileName property) and the destination (DestinationFile property) property.

You initiate an encode operation by calling the MIMEEncode method which fires the EncodingStarted event. When you call the MIMEEncode method, the EncodingStarted event fires. You can gather data about the progress of the encode operation through the Encoded event.

See Also

EncodingStarted, MIMEEncode, SourceFileName


 EncodingStarted Event

Applies To

CIMIME

Purpose

The EncodingStarted event notifies the Visual Basic application that the encoding operation has started and that the SourceFileSize property can now be read.

Syntax

Sub CIMIME1_EncodingStarted()

Comments

The EncodingStarted event fires when the CIMIME control has opened the source file (SourceFileName property) and the destination file (DestinationFileName property) and the encoding operation has started.

You initiate an encode operation by calling the MIMEEncode method. When all of the data is encoded, the EncodingFinished event fires. You can gather data about the progress of the encode operation through the Encoded event.

See Also

Encoded, EncodingFinished, DestinationFileName, DestinationFileSize, MIMEEncode, SourceFileName


 MIMEDecode Method

Applies To

CIMIME

Purpose

The MIMEDecode method initiates the decode operation on a file (named by the SourceFileName property). The result of the decode operation resides in the file identified by the DestinationFileName property.

Syntax

Boolean = CIMIME.MIMEDecode

Data Type

Integer

Comments

When the return code (Boolean) is True, MIMEDecode succeeded; when false, it failed.

You must set the SourceFileName and DestinationFileName properties before calling the MimeDecode method. If you do not set them, CIMIME displays a dialogbox that prompts you for the names. The MIMEDecode method updates the SourceFileSize and DestinationFile Size properties.

MIMEDecode initiates the decoding operation which causes the DecodingStarted event to fire. When the decoding operation completes, the DecodingFinished event fires. If you set the FireStatus property to True, the Decoded event fires during the decoding operation (depending on the file size). You can gather data about the progress of the decode operation with the Decoded event.

See Also

DestinationFileName, Encoded, EncodingFinished, EncodingStarted, MIMEDecode, SourceFileName


 MIMEEncode Method

Applies To

CIMIME

Purpose

The MIMEEncode method initiates the encode operation on a file (named by the SourceFileName property). The result of the encode operation resides in the file identified by the DestinationFileName property.

Syntax

Boolean = CIMIME.MIMEEncode

Data Type

Integer

Comments

When the return code (Boolean) is True, MIMEEncode succeeded; when False, MIMEEncode failed.

You must set the SourceFileName and DestinationFileName properties before calling the MIMEEncode method. If you do not set these properties, the CIMIME control displays a dialogbox that prompts you for the names. The MIMEEncode method updates the SourceFileSize and DestinationFile Size properties.

MIMEEncode initiates the encoding operation which causes the EncodingStarted event to fire. When the encoding operation completes, the EncodingFinished event fires. If you set the FireStatus property to True, the Encoded event fires during the decoding operation (depending on the file size).

See Also

DestinationFileName, Encoded, EncodingFinished, EncodingStarted, MIMEDecode, SourceFileName


 General Tab

Applies To

CIMIME

This custom tab lets you set these custom properties:

SourceFileName

DestinationFileName

ContentType

FireStatus