A Netscape extension is designed and built in parts, as depicted in the following illustration:
The top three levels are modules, or logical groupings, of an extension and the components within an extension. You design extensions within these modules, which are described in the following sections:
Each of the above modules corresponds to individual IDL files: one file for the extension, one file for each access module, and one file for each service module. KIDL is used in different ways depending on the module of the extension you are designing. The IDL files are then used as input to the KIDL Compiler, which creates the extension source code and method stubs. These concepts and procedures are described in later sections.
Extension Module
The extension module represents the extension as a whole. It is a grouping of the interfaces and services that compose the extension. The extension module contains the access module and the service module, and everything those modules contain.
The IDL file for the extension module is very simple. Below is an example of the IDL code as it appears in an actual extension module IDL file.
//
// This file is generated by KIDL - do not edit
//
global [package(testextension), extension_language(java_code),
extension_name(TestExtension_EXT)]
package extension;
typedef long time_t;
typedef unsigned int size_t;
typedef HRESULT SCODE;
typedef _GUID GUID;
typedef GUID IID;
typedef GUID CLSID;
typedef IID REFIID;
typedef CLSID REFCLSID;
typedef GUID REFGUID;
#include "KIVA.idl"
#include "myiext.idl"
This file is named TestExtension_EXT.idl, as denoted by the extension_name decoration in the first lines of code.
Note the # include statements at the bottom of the IDL file. The first includes the Netscape Application Server access module IDL file, which contains the support interfaces necessary for inter-operating with the Netscape Application Server. The second # include statement refers to the extension access module IDL file, which describes the interfaces created for the extension.
The service modules are included in the extension by referring to the extension module using a # include, as described later.
The entire content of the extension IDL file is generated by the Netscape Extension Builder Designer, so you don't have to write any of it.
Access Module
The access module is a grouping of the interfaces used by application components to access Netscape extension objects. The interfaces within the access module have no implementation details and are simply the specifications of the operations a client, by invoking the methods exposed by the interfaces, can perform when interacting with an object.
For example, you might define an IQueryAccount interface with a GetBalance( ) method. This method probably contains several parameters. Within the access module, the IDL code would specify that an IQueryAccount interface was going to exist, as well as the GetBalance( ) method and the parameters of that method. Basically, the access module specifies the names of the interfaces, methods, and parameters available to the application components. Below is an example of the IDL code as it appears in an access module IDL file.
//
// This file is generated by KIDL - do not edit
//
[package(testextension)]
module myiext
{
[local, object, uuid(90BB7EB0-518F-11D1-A1AA-006008293C54)]
interface IExtMain : IGXObject
{
HRESULT GetMyName(
[out] LPSTR pName,
[in] unsigned long nameSize);
HRESULT CreateFirst(
[out] IExtFirstInterface** ppFirst);
HRESULT CreateSecond(
[out] IExtSecondInterface** ppSecond);
};
[local, object, uuid(B0399FF0-518F-11D1-A1AA-006008293C54)]
interface IExtFirstInterface : IGXObject
{
HRESULT DeliverTo(
[in] LPSTR deliverWhat,
[in] LPSTR toWhom);
HRESULT TurnUp(
[in] DWORD increment,
[out] IExtSecondInterface** ppNewGuage);
HRESULT SetFilmSize(
[in] DWORD filmSize);
HRESULT GetFilmSize(
[out] DWORD* pFilmSize);
};
[local, object, uuid(D94AC9F0-518F-11D1-A1AA-006008293C54)]
interface IExtSecondInterface : IGXObject
{
HRESULT GetDescription(
[out] LPSTR pDesc,
[in] unsigned long descSize);
HRESULT SetHighWaterMark(
[in] DWORD newMark);
};
}
In this example, the file is named myIExt.idl. There are three interfaces defined in this access module: the IExtMain, the IExtFirstInterface and the IExtSecondInterface. These are specified on the lines that begin with the keyword interface. Each interface is a client of (denoted by the colon) the IGXObject interface, from which all interfaces are derived.
Within each interface are the specifications for the methods that clients can use to invoke operations from the object or objects that will implement these interfaces. Methods are typically denoted with the HRESULT keyword. In the parentheses after each method are the parameters of the method along with a scope notation (denoted in the square brackets) of whether it is an in or out parameter.
Service Module
The service module is a grouping of coclasses. A coclass is a design specification of a class and becomes a class after the service module IDL file is compiled.
In the service module, coclasses typically implement one or more of the interfaces defined in the access module. When implementing those interfaces, you can add decorations to the interfaces, methods and parameters. Decorations describe a portion of the implementation details for how a coclass becomes a class. For example, a decoration can provide information to the KIDL Compiler that a certain interface is going to have a Java access layer that supports calls from Java application components.
Implementation details are not specified in the access module to simplify extension building and to support multiple interface implementation.
Multiple interface implementation allows for different implementations of the same interface. It is easier to assign decorations on a coclass basis, rather than define two interfaces, which would appear identical to the application component layer.
For example, you could define two coclasses that implement the same interface, but implement that interface in different ways. Within the service module you might have a Java version coclass called myExtJavaService as well as a C++ version coclass called myExtC++Service. Each coclass would implement the same interface. However, the implementation of the interface in the Java service would use a Java Access Layer decoration, whereas the C++ coclass implementation would not use the Java Access Layer decoration. This example is depicted in the following illustration:
Below is an example of the IDL code as it appears in a service module IDL file, named myext.idl. Note how the first line of code includes the extension module.
//
// This file is generated by KIDL - do not edit
//
#include "TestExtension_EXT.idl"
[package(testextension.myext)]
module myext
{
[uuid(72c1c580-9f31-11d1-a1bb-006008293c54), wrapper_uuid(72c1c581-
9f31-11d1-a1bb-006008293c54)]
coclass CExtModule
{
interface IGXModule
{
Init( pObj);
Uninit( pObj);
}
interface IExtModule
{
GetMyName([size_is(nameSize)] pName, [default_value(512)] nameSize);
CreateFirst([java_class(testextension.myext.CExtFirstClass),
cpp_class(CExtFirstClass)] ppFirst);
CreateSecond([java_class(testextension.myext.CExtSecondClass),
cpp_class(CExtSecondClass)] ppSecond);
}
};
[uuid(72c1c582-9f31-11d1-a1bb-006008293c54), wrapper_uuid(72c1c583-
9f31-11d1-a1bb-006008293c54)]
coclass CExtFirstClass
{
interface IExtFirstInterface
{
DeliverTo( deliverWhat, toWhom);
TurnUp( increment, [java_class(testextension.myext.CExtSecondClass),
cpp_class(CExtSecondClass)] ppNewGuage);
IgnoreThis( pIgnore);
SetFilmSize( filmSize);
GetFilmSize( pFilmSize);
}
};
[uuid(72c1c584-9f31-11d1-a1bb-006008293c54), wrapper_uuid(72c1c585-
9f31-11d1-a1bb-006008293c54)]
coclass CExtSecondClass
{
interface IExtSecondInterface
{
GetDescription([size_is(descSize)] pDesc, [default_value(512)]
descSize);
SetHighWaterMark( newMark);
}
};
}
The definitions of the coclasses, denoted by the coclass keyword, include the interfaces, methods and parameters each coclass implements. Around all of these definitions are decorations, which are contained in square brackets [ ]. Notice how the decorations provide implementation details. Decorating the components of a coclass is covered later in Chapter 4, Designing a Netscape Extension.
Previous
