Win32::Exchange::Mailbox - Exchange 5.5 and Exchange 2000 mailbox maintenance functions


NAME

Win32::Exchange::Mailbox - Exchange 5.5 and Exchange 2000 functions


SYNOPSIS

  $provider = Win32::Exchange::Mailbox->new($info_store_server)) ||
      die " - error creating new object\n';

  #--- Exchange 5.5
  $mailbox = $provider->CreateMailbox($info_store_server,$mailbox_alias_name);
  if (!$mailbox) {
    die "Error creating mailbox\n";
  }
  print "Create successful\n";
  $mailbox->SetAttributes(\%Attributes);
  $mailbox->SetOwner("$domain\\$mailbox_alias_name");
  $mailbox->SetPerms(\@Perms);

  #--- Exchange 2000
  $mailbox = $provider->CreateMailbox($info_store_server,
                                           $pdc,
                                           $mailbox_alias_name,
                                           "domainname.com") ||
    print 'Mailbox create failed\n';
  $mailbox->Win32::Exchange::SetAttributes(\%Attributes) ||
        print 'Set Attributes failed\n';
  $mailbox->SetPerms(\@Perms);


DESCRIPTION

For now, this module creates and modifies Exchange 5.5 and 2000 mailboxes, has growing support for distribution lists, and some server API queries. Eventually it will do more, but for now, that's it. Kind of vague.. isn't it?

Win32::Exchange uses Win32::OLE exclusively (and technically is just a wrapper for the underlying OLE calls) so feel free to look at them, and make a suggestion or two.

Exchange 5.5 mailbox creation uses the LDAP interface on the Exchange server exclusively. If the LDAP protocol is disabled on your Server, you will not be able to use this module until you turn it on.

Exchange 2000 mailbox creation is a little bit different because it is based on COM objects, instead of LDAP, and you need the Exchange 2000 client tools loaded on the box you want to do the creation on in order to work correctly. These are kind of modest requirements, but please check the NOTES section for more on software requirements and good ideas.

All methods return 0 (or undef) on failure and 1 for success unless otherwise noted.

Functions

$provider = Win32::Exchange->new($server_name | $version);
The new() class method starts a new instance of an Exchange provider object. It returns a reference to this object or undef if the creation fails.


$provider = Win32::Exchange::Mailbox->new($server_name); #new performs a check on your exchange server for versioning
$provider = Win32::Exchange::Mailbox->new($version); #creates an object suitable for a $version server.. ("5.5" or "6.0")

Win32::Exchange::GetVersion can return an acceptable version number for your Exchange server.

$provider->AddDLMembers($info_store_server,$dl_name,\@new_dl_members[,1]);#Exchange 5.5 sending an alias name
$provider->AddDLMembers($info_store_server,$dl_dn,\@new_dl_members);#Exchange 5.5 sending a "distinguished name"
$provider->AddDLMembers($dl_name,\@new_dl_members);#Exchange 2000
The only noticable difference between Exchange 5.5 and 2000 for this call are the parameters sent to it, and the provider version that should be sent. In either case, both functions check parameters and provider versions, so you shouldn't hit any snafus.

The Exchange 5.5 version now accepts either that "alias name" or the "distinguished name" of both the distribution list and the mailbox. As well, the module can search for both the DL and MB "distinguished name" if you choose not to send it (but send the ontional "1" signifying you want it to search). If you send an alias name and do not choose to search for it, the module will expect that your alias is in the default container.
#Exchange 5.5
if ($provider->AddDLMembers($info_store_server,$dl_name,/@new_dl_members),1) { #Search for $dl_name
print "Added members successfully\n";
}

#Exchange 2000
if ($provider->AddDLMembers($dl_name,/@new_dl_members)) {
print "Added members successfully\n";
}



$provider->CreateMailbox($server_name,$mailbox_name,[$org,$ou]);#Exchange 5.5
$provider->CreateMailbox($server_name,$dc_name,$mailbox_name,$mail_domain,[$storage_group,$mailbox_store]);#Exchange 2000
$provider->CreateMailbox($server_name,$dc_name,$mailbox_name,$mail_domain,[$mailbox_store_dn]);#Exchange 2000 using dn
The CreateMailbox() function behaves differently depending on which type of provider it is passed (CDO.Person [E2K] or ADsNamespaces[5.5]). As well, the arguments for the Exchange 5.5 and 2000 functions are different.

When making Exchange 2000 Mailboxes, it should be noted that if you are using multiple "storage groups", or multiple "mailbox stores" on the Exchange Server, the presence of $storage_group and $mailbox_store are not optional (unless replaced by a valid mailbox store distinguished name as the fifth parameter), as the function will fail because it doesn't know where to put your new mailbox.

Lastly, if you plan on running LocateMailboxStore before the CreateMailbox, you can pass the distinguished name of the "located" mailbox store instead of the "storage group" and "mailbox store" names.



$provider->GetMailbox($server_name,$mailbox_name,[$org,$ou]);
$provider->GetMailbox($server_name,$mailbox_name,[1]);#Exchange 5.5
The GetMailbox() function is implemented for Exchange 5.5 and 2000.

The base object that is returned for Exchange 2000 mailboxes is the LDAP user object, and the object that is returned for Exchange 5.5 is the 5.5 mailbox object.

Optionally, you can tell the function to search for your object if it does not reside in the default container (cn=Recipients,ou=yourOU,o=YourO), or send it the "distinguished name" of your object (useful in Exchange 5.5 only).

$mailbox = $provider->GetMailbox($info_store_server,$mailbox_alias_name,$org,$ou);
if ($mailbox) {
print "Mailbox exists\n";
}

- OR - when you want to search for the mailbox... (Exchange 5.5 only)

$mailbox = $provider->GetMailbox($info_store_server,$mailbox_alias_name,1);
if ($mailbox) {
print "Mailbox exists\n";
}


$mailbox->GetOwner($nt_user,[$sid_type]);#Exchange 5.5
The GetOwner() method takes an Exchange 5.5 mailbox object like one provided by GetMailbox() or CreateMailbox() along with a variable to store the results in, and an optional "SID type", in order for the function to return a string type of your choosing.

This function defaults to ADS_SID_WINNT_PATH if no sid_type is specified. I don't believe there is an E2K equivelant.

$mailbox->GetOwner($nt_user,0x2) || print 'Error getting owner\n'; #0x2 == ADS_SID_SAM


$user_obj->MailEnable([$address]);#E2K only (for now)
This method allows you mail-enable an AD user account. Optionally, you can set the address to send mail for the user if it was to be redirected to an off-site account (perhaps, the user's hotmail.com, juno.com, or yahoo.com mail account).

if ($user_obj->MailEnable("pcgeek@bigfoot.com") {
print "Success!";
}


$mailbox->SetAttributes(\%attrs);Exchange 5.5
$ad_user_object->SetAttributes(\%attrs);Exchange 2000
The SetAttributes() method takes a specially formed hash structure, and is different depending on which version of Exchange you are trying to set attributes for:

Exchange 5.5:

$Exchange_Info{'Deliv-Cont-Length'}='6000';
$Exchange_Info{'Submission-Cont-Length'}='6000';
$Exchange_Info{'givenName'}="This";
$Exchange_Info{'sn'}="Isatest";
$Exchange_Info{'cn'}=$mailbox_full_name;
$Exchange_Info{'mail'}="$mailbox_alias_name\@manross.net";
$Exchange_Info{'rfc822Mailbox'}="$mailbox_alias_name\@manross.net";

push (@$Other_MBX,"RFAX:$Exchange_Info{'cn'}\@");
push (@$Other_MBX,"smtp:secondary\@$mail_domain");
push (@$Other_MBX,"smtp:tertiary\@$mail_domain");
$Exchange_Info{'otherMailbox'}=$Other_MBX;

Note:
See Also (Exchange 5.5):
Exchange 5.5 and ADSI (ADSI Exchange)

Exchange 2000:

push (@$proxies,'SMTP:'.$mailbox_alias_name.'@manross.net');
push (@$proxies,'smtp:secondary@manross.net');
push (@$proxies,'smtp:tertiary@manross.net');
$Attributes{"IMailRecipient"}{ProxyAddresses} = $proxies;
$Attributes{"IMailRecipient"}{IncomingLimit} = 6000;
$Attributes{"IMailRecipient"}{OutgoingLimit} = 6000;
$Attributes{"IMailboxStore"}{EnableStoreDefaults} = 0;
$Attributes{"IMailboxStore"}{StoreQuota} = 100;
$Attributes{"IMailboxStore"}{OverQuotaLimit} = 120;
$Attributes{"IMailboxStore"}{HardLimit} = 130;

See Also (Exchange 2000):
Interfaces and attributes


$mailbox->SetOwner($user);
The SetOwner() method takes a string reference (ex. "DOMAIN\USERNAME") and is currently only applicable for use in setting the owner on Exchange 5.5 mailboxes (the "Assoc-NT-Account" property of the mailbox). I don't believe there is an E2K equivelant.

$mailbox->SetOwner("DOMAIN\username") || print 'Error setting owner\n'


$mailbox->SetPerms(\@users);
The SetPerms() method takes an array reference of user or group names. This function works on Exchange 5.5 and Exchange 2000 mailboxes. The Exchange 2000 version requires Service Pack 1, with a hotfix, Service Pack 2, or later Service pack release, and is reccommended that the Exchange Client Tools be of the same Service Pack level as the server.

push (@PermsUsers,"$domain\\$mailbox_name");
push (@PermsUsers,"$domain\\Some Group");
$mailbox->SetPerms(\@PermsUsers) || print 'Error setting perms\n'


Module Options

Currently there are none, but I intend to make DEBUG a passable parameter as it is currently hard-coded to 1 (enabled).

EXAMPLES

use Win32::Exchange;
use Win32::AdminMisc;

$domain = Win32::DomainName();
$pdc = Win32::AdminMisc::GetPDC($domain);
$mailbox_alias_name='thisisatest';
$mailbox_full_name="This $mailbox_alias_name Isatest";
$info_store_server="HOMEEXCH2";

if (!Win32::Exchange->GetVersion($info_store_server,\%ver) ) {
  die "$rtn - Error returning into main from GetVersion\n";
}

print "version      = $ver{ver}\n";
print "build        = $ver{build}\n";
print "service pack = $ver{sp}\n";

if (!($provider = Win32::Exchange::Mailbox->new($ver{'ver'}))) {
  die "$rtn - Error returning into main from new ($Win32::Exchange::Mailbox::VERSION)\n";
}

if ($ver{ver} eq "5.5") {
  if (!Win32::Exchange::GetLDAPPath($info_store_server,$org,$ou)) {
    print "Error returning into main from GetLDAPPath\n";
    exit 1;
  }
  print "GetLDAPPath succeeded\n";
  if ($mailbox = $provider->GetMailbox($info_store_server,$mailbox_alias_name,$org,$ou)) {
    print "Mailbox already existed\n";
    if ($mailbox->SetOwner("$domain\\$mailbox_alias_name")) {
      print "SetOwner in GetMailbox worked!\n";
    }
  } else {
    $mailbox = $provider->CreateMailbox($info_store_server,$mailbox_alias_name,$org,$ou);
    if (!$mailbox) {
      die "error creating mailbox\n";
    }
    print "We created a mailbox!\n";
  }

  $Exchange_Info{'Deliv-Cont-Length'}='6000';
  $Exchange_Info{'Submission-Cont-Length'}='6000';
  $Exchange_Info{'givenName'}="This";
  $Exchange_Info{'sn'}="Isatest";
  $Exchange_Info{'cn'}=$mailbox_full_name;
  $Exchange_Info{'mail'}="$mailbox_alias_name\@insight.com";
  $Exchange_Info{'rfc822Mailbox'}="$mailbox_alias_name\@insight.com";

  $smtp="smtp:another_name_to_send_to\@$mail_domain";
  push (@$Other_MBX,$smtp);
  #be careful with 'otherMailbox'es..  You are deleting any addresses that may exist already
  #if you set them via 'otherMailbox' and don't get them first (you are now forewarned).
  $Exchange_Info{'otherMailbox'}=$Other_MBX;

  $mailbox->SetAttributes(\%Exchange_Info);
  $mailbox->SetOwner("$domain\\$mailbox_alias_name");

  my @PermsUsers;
  push (@PermsUsers,"$domain\\$mailbox_alias_name");
  push (@PermsUsers,"$domain\\Exchange Perm Users"); #Group that needs perms to the mailbox...

  $mailbox->SetPerms(\@PermsUsers);
  my @new_dl_members;
  push (@new_dl_members,$mailbox_alias_name);
  $provider->AddDLMembers($info_store_server,"newdltest",\@new_dl_members);

} elsif ($ver{ver} eq "6.0") {
  $storage_group = ""; #you'd need to define this if you had more than 1 storage group on 1 server.
  $mailbox_store = ""; #you'd need to define this if you had more than 1 mailbox store on 1 or more storage groups.
  if (Win32::Exchange::LocateMailboxStore($info_store_server,$storage_group,$mailbox_store,$store_name,\@counts)) {
    print "storage group = $storage_group\n";
    print "mailbox store = $mailbox_store\n";
    print "located store distinguished name= $store_name\n";
    print "$info_store_server\n";
    print "  Total:\n";
    print "    storage groups = @counts[0]\n";
    print "    mailbox stores = @counts[1]\n";
  }
  if ($mailbox = $provider->CreateMailbox($info_store_server,
                                              $pdc,
                                              $mailbox_alias_name,
                                              "insight.com",
                                              $store_name
                                             )
     ) {
    print "Mailbox create succeeded\n";
  } else {
    die "Failure is the option that you have selected!\n";
  }
  #be careful with proxy addresses..  You are deleting any addresses that may exist already
  #if you set them via ProxyAddresses (you are now forewarned).
  push (@$proxies,'SMTP:'.$mailbox_alias_name.'@manross.net');
  push (@$proxies,'smtp:secondary@manross.net');
  push (@$proxies,'smtp:primary@manross.net');
  push (@$proxies,'smtp:tertiary@manross.net');
  $Attributes{"IMailRecipient"}{ProxyAddresses} = $proxies;
  $Attributes{"IMailRecipient"}{IncomingLimit} = 6000;
  $Attributes{"IMailRecipient"}{OutgoingLimit} = 6000;
  $Attributes{"IMailboxStore"}{EnableStoreDefaults} = 0;
  $Attributes{"IMailboxStore"}{StoreQuota} = 100; #at 100KB starts getting warnings
  $Attributes{"IMailboxStore"}{OverQuotaLimit} = 120; #at 120KB can't send...
  $Attributes{"IMailboxStore"}{HardLimit} = 130; #at 130KB, can't do anything...
  if (!$mailbox->Win32::Exchange::SetAttributes(\%Attributes)) {
    die "Error setting 2K Attributes\n";
  } else {
    print "Set Attributes correctly\n";
  }
  my @PermsUsers;
  push (@PermsUsers,"$domain\\$mailbox_alias_name");
  push (@PermsUsers,"$domain\\Exchange Perm Users"); #Group that needs perms to the mailbox...

  $mailbox->SetPerms(\@PermsUsers);
  exit 1;
}

NOTES

Incompatabilities

Bugs and Limitations


SEE ALSO


AUTHORS

This module is based on an Exchange 5.5 mailbox creation script that has been traveling around the Internet and Activestate's mailing list archives for years.

I picked up on the thread that started my mailbox creation frenzy in 1999, and have been modifying the subroutines ever since.

With the advent of Exchange 2000, another script came to light, that tried to parse the Storage Group name and Mailbox Store names into an incredibly long string to allow for Exchange 2000 mailbox creation (circa 2001?).

I knew that the entire string had to be all parsed together somewhere in the Directory, and it was just a matter of finding it.

It was; LocateMailboxStore is an implementation of that idea.

As it turns out, there are a lot of tricks like LocateMailboxStore that have helped develop this module from a string concatenation mess into a lot of fancy searches for the complete ldap paths and distinguished names that power mailbox creation.

Most of the fancy searches were created by poking around in the objects themselves with ADSVW.EXE (an ADSI SDK tool), and then writing an ADODB search to return the right result set.

Thanks for taking the time to read all of this..

I'd like to extend thanks to the following:

Please send questions, comments or suggestions about this module to Steven Manross <steven@manross.net>.


VERSION

Version 0.036 May 5, 2003

Copyright

Microsoft, Active Directory, ADSI, Windows, Windows NT, MSDN, and Exchange are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.


 Win32::Exchange::Mailbox - Microsoft Exchange mailbox related functions