Application

The root Application object. All other GroupWise objects are contained by this object.

Properties

The following table lists properties along with their access and descriptions.

Property

Access

Description

Application

R/O

Application. The Application object; provided for consistency.

BuildNumber

R/O

A number that identifies different versions of Field Test File (FTF) patches and indicates when a fix was included. For example, if you receive two FTF updates for version 6.5.4, you can tell the difference between the two files by the BuildNumber.

CommandLine

R/O

String. The command line that was used in the Login method to log in to the root account. Returns an empty string ("") if not logged in.

FullName

R/O

String. Fully-qualified path\file name of Windows executable.

LoginError

R/O

String. The LoginError property will return the engine error that caused the problem.

MainAccounts

R/O

Accounts collection. The accounts logged into through the Login or MultiLogin methods.

MajorVersion

R/O

Long. The major number (the number before the period) in the application’s version number. Example: In the application version number 2.1, 2 is the MajorVersion.

MinorVersion

R/O

Long. The minor number (the number after the period) in the application’s version number. Example: In the application version number 2.1, 1 is the MinorVersion.

MultiLoginAddressBookSupport

R/W

Boolean. If TRUE, accounts created by calling MultiLogin do not use MAPI address book methods to retrieve their data, which allows each MultiLogin account to see the address book data for each user. If FALSE, all accounts use the Address Book data for the first account logged into by GroupWise.

Name

R/O

DEFAULT. String. The name of this application.

Parent

R/O

Application. A reference to this object; provided for consistency.

ProxyAccounts

R/O

Accounts collection. The proxy accounts currently being used.

ProxyHistory

R/O

Addresses collection. The list of all addresses to which the root user has proxied.

RemoteAccount

R/O

Account. The remote account that corresponds to the root account. Returns nothing if (1) the root account is not a master account whose remote account is currently accessible, or if (2) the root account is not logged in.

RootAccount

R/O

Account. The root account. Returns nothing if the account is not logged in.

VersionRevision

R/O

Represents the service path revision number and is an extension of the MajorVersion and MinorVersion properties. For example, if your GroupWise version number is 6.5.4, 6 is the MajorVersion, 5 is the MinorVersion, and 4 is the VersionRevision.

Methods

Account Login([String UserID], [String CommandLine], [String Password], [LoginConstants WhenToPrompt], [VARIANT Reserved])

Logs in to the root account. Returns the root Account object. When an exception is thrown, returns the object pointer set to NULL. Adds the root account to the MainAccounts collection. Searches the operating system and NetWare for login information, such as user ID and password, not provided in parameters.

  • When you omit WhenToPrompt or when WhenToPrompt = egwPromptIfNeeded and the Login search returns no information, Login displays a dialog box for the user. These are the only circumstances in which the Object API provides a user interface.

  • When WhenToPrompt = egwNeverPrompt, Login throws an exception instead of displaying a user dialog box. Always omit the Reserved parameter.

To log in as a different user, you must either release all currently held objects, or use the MultiLogin method.

Account MultiLogin(String UserID, String CommandLine, String Password, LoginConstants WhenToPrompt, VARIANT Reserved)

Lets you to login to multiple accounts with the same application. Logs in to the account specified by UserID. Returns the Account object. When an exception is thrown, returns the object pointer set to NULL. Adds the account to the MainAccounts collection. It does not affect the root login, so Notify, the GroupWise client, and other such applications are not automatically logged in, and the RootAccount object is empty. The parameters for MultiLogin are the same as the parameters for Login, except that the UserID and Password parameters are both required. The one exception to this is when a Trusted Application is used. The MultiLogin method requires only a UserID with a Trusted Application. Use the Account object's Refresh method to see changes made to a MultiLogin account. Changes made to one MultiLogin account are not automatically updated in other MultiLogin accounts.

A Trusted Application can be installed by a GroupWise Administrator. Trusted Applications can use the MultiLogin method to attach to any user's online mail box. (Trusted Applications cannot automatically login to a Remote or Client/Cache mailbox.) This Trusted Application is given an Application Name and an Application Key by the GroupWise Administration system.

Account Proxy(VARIANT User)

Proxies as another user. Returns the proxy Account object. When an exception is thrown, returns the object pointer set to NULL. Adds the new proxy account to the ProxyAccounts collection. User may be a UserID string, or a user’s Address object.

SetTrustedApplicationCredentials(String TrustedAppName, String TrustedAppKey)

Sets the Trusted Application name and Trusted Application Key into the Object API.

A Trusted Application can be installed by a GroupWise Administrator. As part of this installation, a Trusted Application Name is passed to the GroupWise system, which returns a Trusted Application Key as a string. The Trusted Application must store this Trusted Application Name and Key pair.

NOTE:The Key is a 65-byte string (64 bytes of data and a NULL byte).

When an application wants to become a Trusted Application by using the Object API, that application provides the Trusted Application Name and Key to the Object API by calling SetTrustedApplicationCredentials.

Once an application supplies the Trusted Application, it can call the MultiLogin method to attach to any users' on-line mail box. (Trusted Applications cannot automatically log in to a Remote or Client/Cache mailbox.) The vUserID and vCommandLine parameters are filled in with the appropriate commands. If a Password is provided (using either the vPassword parameter or the command line), it must be the correct password to access this box. If a password is not provided, the Object API attempts to log in to this users box using the Trusted Application Name and Key. The GroupWise engine verifies the Trusted Application credentials for this machine, including the Trusted Application Name and Key. If the Trusted Application credentials are certified, the application may access the user's database as if they were the user themselves.

For example, if my Trusted Application was Named EncryptMessages and was given a key of 1234567890, the application calls the SetTrustedApplicationCredentials method (using C++ syntax) as in the following:

gw.Application->SetTrustedApplicationCredentials ("EncryptMessages", "1234567890");

The Application then logs in to user JDoe by calling MultiLogin as in the following:

gw.Application->MultiLogin("JDoe", "/ipa-199.99.99.99 /ipp-1677", NULL, egwPromptNever, NULL, &dispAccount);

If the Application Name and Application Key are found in the GroupWise Post Office database, the Trusted Application is allowed to connect to JDoe's mailbox with full access to create messages, read items, etc.

Remarks

The Application object does not need to be refreshed because it is always up to date.