Setting up your programming environment for P&M depends primarily on the goals of your project. The general requirements for each programming language are listed below. For specific cases such as with examples or with one of the samples, any additional steps required are listed in that respective section.
Base Requirements
The recommended base requirements for using C or C++ to develop applications using Site Server 3.0 are listed below:
P&M-Specific Requirements
Programmers can get the COM interface declarations and universally unique identifiers (UUIDs) used to access the P&M COM objects in two ways:
Using MIDL
If you are unfamiliar with the process of generating header files for C or C++ from the interface definition language (IDL) files or type libraries, the following example demonstrates this process using the IDL definition for the ObjCreator coclass and the AuoConfig coclass. The IDL definitions for these COM classes and their respective COM interfaces are found in the accompanying IDL files named objcreator.idl and auo.idl. A complete discussion of these objects can be found in the object overview section as well as in the reference section.
The first step is to copy the IDL file to the project directory. Then simply run the MIDL compiler, passing the name of the IDL file as the primary argument as follows:
MIDL objcreator.idl |
|
MIDL auo.idl |
This will produce the necessary header files, objcreator.h, objcreator_i.c, auo.h, and auo_i.c, along with some other files. Include these files in source code where necessary. The .h file contains the interface declarations, and the .c file contains the UUID (GUID) definitions:
#include “objcreator.h”
#include “objcreator_i.c”
#include “auo.h”
#include “auo_i.c”
If you use an integrated development environment such as Microsoft Developer Studio® version 5.0, you can simply add the .idl file into the project, and then set a custom build step for the file. This build step should be essentially the same as the command listed above. For the output file names, you can use the defaults generated by MIDL, which in this example would be objcreator.h and objcreator_i.c for the objcreator.idl file, and auo.h and auo_i.c for the auo.idl file.
After this is done, and the necessary include files are there, you can specify the types for interfaces as well as refer to GUIDs using the usual naming convention:
main()
{
CoInitialize(NULL);
IObjCreator* pIObjCreator = 0;
IDispatch* pIDisp = 0;
IAuoConfig* pIAuoConfig = 0;
BSTR bszProgID = SysAllocString(L”MemAdmin.AuoConfig.1”);
BSTR bszServer = SysAllocString(L””); // localhost
HRESULT hr = S_OK;
hr = CoCreateInstance( CLSID_ObjCreator,
NULL,
CLSCTX_SERVER,
IID_IObjCreator,
(void**)&pIObjCreator);
if(FAILED(hr)) { ... } // deal with error here
// Get the IDispatch interface on the AuoConfig object
hr = pIObjCreator->CreateObjAuth(bszProgID,bszServer,(void**)&pIDisp);
if(FAILED(hr)) { ... } // deal with error here
// Fetch the IAuoConfig interface
hr = pIDisp->QueryInterface(IID_IAuoConfig,(void**)&pIAuoConfif);
if(FAILED(hr)) { ... } // deal with error here
// Go on to use the AuoConfig object
return 1;
}
}
The necessary IDL files accompany this SDK. However, you can generate the IDL by using a tool such as oleview.exe. In this case, bind to the desired type library using oleview.exe and select the Save As option from the File pull-down menu. This will save the contents of the library as an IDL file with the name you choose.
Using the #import Directive with the Microsoft Visual C++ 5.0 Compiler
A simpler and perhaps more "C++-intuitive" way to get the necessary information about COM classes into a code module is to use the #import directive supported by the Visual C++ 5.0 compiler. When the preprocessor hits an #import directive, it binds the ITypeInfo interface on the type library specified and then generates and includes two header files with extensions .tlh and .tli. These header files use a set of wrapper C++ classes to more intuitively present the COM class and its exposed interfaces. The wrapper class automatically calls the IUnknown methods QueryInterface, AddRef, and Release and can be thought of as a smart pointer. Additionally, helper methods are constructed in the new class to help deal with methods that contain BSTR and VARIANT data types. Properties are made more intuitive through the use of the declspec() function, removing the need to place the "get_" and "put_" prefixes on them. The wrapper methods also use a standard COM error object wrapper class to automatically populate IErrorInfo interface information when a COM exception occurs. These exceptions can be caught using the C++ standard try{} catch(){} blocks. The following example demonstrates the process of using the import directive to access the AuoConfig COM object.
#include <iostream.h>
#import “c:\\Winnt\\System32\\objcreator.dll” no_namespace
#import “c:\\Microsoft Site Server\\bin\\P&M\auo.dll” no_namespace
main()
{
CoInitialize(NULL);
_bstr_t ProgID = “MemAdmin.AuoConfig”;
_bstr_t Server = “”;
IObjCreatorPtr Creator = new IObjCreatorPtr(_uuidof(ObjCreator));
try
{
IAuoConfigPtr AuoConfig = Creator->CreateObjAuth(ProgID,Server);
}
catch( _com_error Err )
{
cout << “Exception caught when trying to create AuoConfig” << endl;
cout << “Description: “ << Err.Description() << endl;
cout << “HRESULT value: “ << Err.Error() << endl;
cout << “Error Source: “ << Err.Source() << endl;
exit(0);
}
... // go on to use the AuoConfig
return 1;
}
As you can see, this greatly simplifies working with these objects, and makes working with the COM objects much like working with native C++ classes. Many of the examples discussed in this guide demonstrate the use of the #import directive.
A complete description of the MIDL compiler, including the various options it supports, and the C++ compiler #import directive can be found in the Microsoft Developers Network CD or online library.
If you plan on using Java to develop applications that use the P&M COM objects, you should acquire the latest Java SDK, version 2.01. The Java compiler that ships with Microsoft® Developer Studio® 97 (Microsoft® Visual J++™) has been superseded by this compiler. Many COM-related improvements exist in this latest SDK release.
In order to access the COM objects exposed by P&M, you need to generate the necessary interface and COM Java classes. This is done using the Java SDK tool JActiveX, with the primary argument being the path to a type library containing the IDL information. For example, to generate the Java classes necessary to access the P&M administrative objects, you need the coclass ObjCreator and its interfaces translated to Java classes. First make sure you have the Java SDK bin directory defined in your PATH, and then run:
JActiveX c:\winnt\system32\objcreator.dll /d c:\myjavaclasses
This creates the class files in subdirectories of "c:\myjavaclasses" in the standard way. Make sure you specify the /d switch, or the classes will be placed below your TrustedLib directory.
Check here for a complete list of all type library locations for the COM objects used in P&M.
After you have the necessary Java classes, you can proceed to import and use them.
As an example, the UserObjects COM class information would be converted like this:
JActiveX c:\Microsoft Site Server\Bin\P&M\auo.dll /d c:\myclasses
JActiveX “c:\Winnt\System32\activeds.tlb” /d c:\myclasses
Java source code with access to this class information might be:
import auo.*;
import activeds.*;
import com.ms.com.Variant;
public class MyClass {
public static void main( String args[] )
{
IUserObjects pIUo = (IUserObjects) new UserObjects();
pIUo.Init("2","JohnS");
IADs pIADs = (IADs) pIUo;
System.out.println(pIADs.Get("GUID"));
String givenName = "Johny B. Goode";
Variant val = new Variant(givenName);
String prop = "givenName";
pIADs.Put(prop,val);
pIADs.SetInfo();
}
}
Most of the P&M COM objects implement pure dual interfaces. Since all dual interfaces are intended to contain only oleautomation types, Visual Basic 5.0 can use the corresponding type library to bind to the COM interface directly. In order to access P&M COM objects through their COM interfaces, you need to add references (under Project/References) to each of the respective type libraries. If you plan on using just the IDispatch interfaces (using CreateObject to fetch interfaces on COM objects), no references are required.
So, for vtable binding:
For example, when creating an instance of the AuoConfig admin COM object, first create an instance of the ObjCreator object and bind to its IObjCreator COM interface. Then create an AuoConfig object with the IAuoConfig interface returned by the ObjCreator object through the CreateObjAuth method. The steps in Visual Basic 5.0 for this are:
Dim oObjCreator as ObjCreator ' only works if Type Lib is referenced
Set oObjCreator = new ObjCreator ' instance, returns IObjCreator
Dim oAuoConfig as AuoConfig
Set oAuoConfig = oObjCreator.CreateObjAuth("MemAdmin.AuoConfig","")
' go on to use the AuoConfig object
oAuoConfig.GetInfo 1
oAuoConfig.GetEntries Names, Providers
A complete list of the type libraries that can be used to reference type information for all P&M interfaces is available in the reference section.
Scripting Languages (Automation)
For automation-enabled scripting languages such as VBScript and JavaScript, little extra information is needed to access the COM objects. In some cases, you may want to prepare a list of constant definitions with human-readable names to make error identification easier.
In general, to access the functionality of COM Automation-compliant objects, simply create the object using the syntax of the particular language:
| VBScript using Microsoft® Windows® Scripting Host (WSH) |
|
|
| JScript using Windows Scripting Host (WSH) |
|
|