Datatypes

The datatypes that the parameters are designated as are expressed in terms of Visual Basic Variant data types. These comprise the following:

VB Variant Data Type    Description

VT_EMPTY                No Value
VT_NULL                 Null Value
VT_I2                   2-byte integer
VT_I4                   4-byte integer
VT_R4                   4-byte real value
VT_R8                   8-byte real value 
VT_CY                   Currency 
VT_DATE                 Date
VT_BSTR                 Binary string
VT_DISPATCH             Automation object
VT_ERROR                Error code
VT_BOOL                 Boolean value 
VT_VARIANT              Variant 
VT_UNKNOWN              IUknown Pointer
VT_UI1                  Unsigned 1-byte character
VT_BYREF                Describes the data as passed by reference
VT_ARRAY                An OLE Safearray

If you want to convert a Perl data type to a VB Variant data type, you need to look at the documentation for the Win32::OLE::Variant module. This is only really relevant, however, if you are using pure Perl scripts to talk to COM objects on the windows platform. In that case, you would need to perform the data conversion from Perl data types to native VB variant data types before passing them to the COM objects you have instantiated in your Perl script.

But that is an adventure for another day.

In our case, we are doing something different. We are writing a COM object in Perl that is returning data to whatever calling context it is being used in. The COM layer will manage the conversion of our return data into the correct VB variant type. Of course it would not be able to do that if we wrote our template description of the WebMail methods incorrectly. In a nutshell, you are going to cause problems for yourself if you state that a particular method in WebMail returns, for example, a VT_DATE. None of the methods actually return a string of the correct format to be coerced into such a variant type.

For WebMail, we are only concerned with 2 VB variant data types. VT_BSTR [ strings ] and VT_BOOL [ booleans ]. All the arguments to the "send()" method are strings, the method returns -1 or 0, a VT_BOOL, and the getError() method, in cases where sending the mail has failed, returns a VT_BSTR [ the actual error message ].

Properties      => {
               'MyIntegerProp' => {
                Type                => VT_I4,
                ReadOnly            => 0,

The properties section is relatively straightforward. List the instance variables of your object, and what VB variant data types that they map to. Also, state whether the properties are read only or not.

And that is it. With all this in mind, it comes as little surprise that generating the template code for the WebMail component is very straightforward. The template we are going to use follows:

=POD
=BEGIN PerlCtrl
    %TypeLib =
    (
    PackageName     => 
    	'WebMail',
    TypeLibGUID     => 
    	'{B3C98206-C910-11D3-B450-00805F9BDE4A}', #do NOT edit line
    ControlGUID     => 
    	'{B3C98207-C910-11D3-B450-00805F9BDE4A}', #do NOT edit line
    DispInterfaceIID=> 
    	'{B3C98208-C910-11D3-B450-00805F9BDE4A}', #or this one
    ControlName     => 
    	'WebMail',
    ControlVer      => 
    	1,  # increment if new object with same ProgID
			       # create new GUIDs as well
    ProgID          => 'WebMail.Mailer',
    DefaultMethod   => '',
    Methods    =>
    {
	'send' =>
	{
	    RetType             =>  VT_BOOL,
	    TotalParams         =>  9,
	    NumOptionalParams   =>  0,
	    ParamList           =>[
				 'from'	=> VT_BSTR,
				 'replyto' => VT_BSTR,
				 'to' => VT_BSTR,
				 'cc' => VT_BSTR,
				 'bcc' => VT_BSTR,
				 'smtp' => VT_BSTR,
				 'subject' => VT_BSTR,
				 'message' => VT_BSTR,
				 'file' => VT_BSTR,
			       ]
	},
	'getError' =>
	{
	    RetType             =>  VT_BSTR,
	    TotalParams         =>  0,
	    NumOptionalParams   =>  0,
	    ParamList           =>[]
	}
    },  # end of 'Methods'
    Properties      => {}
);  # end of %TypeLib
=END PerlCtrl
=cut

Of course, the TypeLibGUID, ControlGUID, and DispInterfaceIID will be different in the case of the template that you generate with the PerlCtrl.pl -t option, but otherwise, you should edit the template to appear exactly as above.

The Steps Needed to Customize the Template
Introduction to Perl on Windows - Table of Contents
Paste the Template Code