mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-08 15:52:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

Author:admin

Browse Source 
Date:2008-09-17T13:53:28.000000Z


git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@3 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
jfiat
2008-09-17 13:53:28 +00:00
parent 4fee9356ea
commit 2ee31ab9c7
763 changed files with 36576 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/com-and-eiffel/access-type.wiki Normal file
View File

@@ -0,0 +1,227 @@
[[Property:title|Access Type]]
[[Property:weight|5]]
Regardless of its location, a COM components can be accessed either directly through interface's virtual table or through OLE Automation.
==Automation==
Accessing a COM component through Automation means using a well known interface to access to a group of methods and properties. This interface is called IDispatch, and it includes the method <eiffel>invoke</eiffel> that allows to call a method, set or get a property on the Automation server. One advantage of that approach is that the interface has a known virtual table layout. As a result, Windows can include a built-in marshaler for that interface (See [[Deeper into COM|Marshaling]] for information on what a marshaler is). The supported types (known as Automation types) and their Eiffel equivalents are listed in the following table:
{|
|-
|
COM Type
|
Eiffel equivalent
|
Description
|-
|
VARIANT_BOOL
|
BOOLEAN
|
Standard boolean
|-
|
unsigned char
|
CHARACTER
|
Standard character
|-
|
double
|
DOUBLE
|
Standard double
|-
|
float
|
REAL
|
2 bytes real
|-
|
int
|
INTEGER
|
Standard integer
|-
|
long
|
INTEGER
|
Standard integer
|-
|
short
|
INTEGER
|
2 bytes integer
|-
|
BSTR
|
STRING
|
Standard string
|-
|
CURRENCY
|
ECOM_CURRENCY
|
Currency value
|-
|
DATE
|
DATE_TIME
|
Standard date
|-
|
SCODE
|
INTEGER
|
Return status
|-
|
Interface IDispatch *
|
ECOM_INTERFACE
|
Automation interface
|-
|
Interface IUnknown *
|
ECOM_INTERFACE
|
Generic interface
|-
|
dispinterface
|
ECOM_INTERFACE
|
Automation interface
|-
|
Coclass Typename
|
TYPE_NAME
|
Component main class
|-
|
SAFEARRAY(TypeName)
|
ECOM_ARRAY [TypeName]
|
Array
|-
|
TypeName*
|
CELL [TypeName]
|
Pointer to type
|-
| VARIANT
| ECOM_VARIANT
| Variant value
|-
| enum
| INTEGER
| Enumeration
|-
|
Decimal
|
ECOM_DECIMAL
|
Decimal value
|}
The other advantage is a more dynamic discovery of the methods and properties of a component at runtime. Indeed the IDispatch interface also includes methods to check whether a method or property is available and, in that case, get its identifier. This process is called late binding and allows component to discover at runtime what are other components functionality.
This approach has also a lot of drawbacks: first, late binding is not an efficient way of calling a function on an interface since its identifier must first be requested and then the function called. That's two round trips which can be expensive in a distributed environment. Second, since the marshaler is built-in, it has to know in advance all the possible types that a function can accept to be able to marshal the corresponding data. There are consequently a limitation on the number of types that one can use in signatures of functions on an Automation compatible interface. The set of available types is called Variant and cover most of the standard types. It does not allow however the passing of complex user defined data types. For these reasons Automation is mostly used in scripting environments (where speed is not an important factor) to accomplish simple tasks.
==Direct Access==
Direct interface access is the preferred way to access remote servers where speed becomes a concern and data types are specific to the application. The first interface pointer on the component is obtained through the class object (see [[Coclass|Class Object]] ). Other interfaces on the component are obtained by calling the QueryInterface function.
As information on any interface cannot be accessed dynamically, the description of the interfaces must be provided to tools that need to handle the components such as the EiffelCOM wizard. The official way of describing components and interfaces is through IDL. Once an IDL file has been written to describe a component it can be compiled with MIDL to generate both a type library and the code for the marshaller specific to that interface.
==EiffelCOM==
The idea in EiffelCOM is the way a component is accessed is implementation detail that the user should not have to deal with. Of course he should be able to choose what kind of access he wants to use but this choice should have no impact on the design of the Eiffel system itself. For that reason, the Eiffel code generated by the wizard follows the same architecture independently of the choice made for interface access and marshalling. The difference lies in the runtime where the actual calls to the components are implemented.
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard|EiffelCOM wizard]] <br/>
[[EiffelCOM Library| EiffelCOM library]] <br/>
[[EiffelCOM: Introduction| Introduction]] <br/>
[[Generalities|Generalities]] <br/>
[[COM Interfaces| COM Interfaces]] <br/>
[[Coclass| Coclasses]] <br/>
[[The Component Location| Component Location]] <br/>
[[Deeper into COM| Deeper into COM]] }}

25
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/com-and-eiffel/coclass.wiki Normal file
View File

@@ -0,0 +1,25 @@
[[Property:title|Coclass]]
[[Property:weight|3]]
We have seen that interfaces can be perceived as views of a component. This conceptual representation actually maps the implementation of an EiffelCOM component since the coclass inherits from the interfaces and implements their deferred features. Indeed, interfaces are deferred classes with all features accessible from outside deferred. The coclass is an Eiffel class that inherits from these interfaces and implements all the features. This design is not specific to Eiffel though and can be found in other languages as well. The coclass defines the behavior of the interface functions. <br/>
==Class Object==
We have seen that interfaces are accessed through interface pointers. But how does a client get hold on one of these?
The answer lies in the class object. The name of this module should really be coclass factory since its goal is to spawn instances of the coclass on request. Class objects are accessed by COM whenever a client request a new instance of the associated component. COM loads the class object and asks it to provide the interface pointer requested by the client.
The way a class object is loaded in memory (this process is called activation) depends on the location of the component (See [[The Component Location|Location]] for a description of the possible locations of a component). If the component is an in-process server then the class object is called directly through the functions exported from the DLL. If the component is an out-of-process server then it provides COM with a pointer to the class object. In both cases, once the component is loaded, COM has access to the class object and can call it would a client request a new instance of a component.
[[Image:com-1|Component Creation]]
The code for the class object is generated by the EiffelCOM wizard so that Eiffel programmers will not have to worry about it.
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard|EiffelCOM wizard]] <br/>
[[EiffelCOM Library| EiffelCOM library]] <br/>
[[EiffelCOM: Introduction| Introduction]] <br/>
[[Generalities|Generalities]] <br/>
[[COM Interfaces| COM Interfaces]] <br/>
[[The Component Location| Component Location]] <br/>
[[Access Type| Access Type]] <br/>
[[Deeper into COM| Deeper into COM]] }}

17
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/com-and-eiffel/com-concepts.wiki Normal file
View File

@@ -0,0 +1,17 @@
[[Property:title|Generalities]]
[[Property:link_title|COM Concepts]]
[[Property:weight|1]]
COM is a binary standard that describes how the component can communicate with the outer-world. The component communicates through well defined interfaces. Each interface is a specification of a group of properties and methods, and it does not contain the implementation of these routines but only their specification (signatures). The actual implementation lies in the coclass. There can be different implementations of a same interface in different coclasses. Finally, each coclass can be instantiated using a class object or class factory. These three notions will be discussed further in the forthcoming paragraphs.
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard|EiffelCOM wizard]] <br/>
[[EiffelCOM Library| EiffelCOM library]] <br/>
[[EiffelCOM: Introduction| Introduction]] <br/>
[[COM Interfaces| COM Interfaces]] <br/>
[[Coclass| Coclasses]] <br/>
[[The Component Location| Component Location]] <br/>
[[Access Type| Access Type]] <br/>
[[Deeper into COM| Deeper into COM]] }}

23
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/com-and-eiffel/com-interfaces.wiki Normal file
View File

@@ -0,0 +1,23 @@
[[Property:title|COM Interfaces]]
[[Property:weight|2]]
Interfaces are at the heart of any COM component. Interfaces are described in the definition file of a component. They consist of a group of semantically related functions that can be accessed by the clients of the component. Although they are a specification, they also have a physical representation. A client can request a pointer on an interface and access the component functions through that pointer. Interfaces are the only possible way to access functions from a component. They enforce information hiding by providing only the public functions to the client.
Interfaces also define the type of a component. Each interface corresponds to a specific view of the component. It can be compared to polymorphism in the Object Oriented world. Whenever an interface from a component is requested, only the functions defined on that interface are accessible as if the component was polymorphically cast into an object of the type of that interface.
The COM specification requires that any interface provides access to all interfaces on the same component. All interfaces should include a specific function called '''QueryInterface''' that will provide a pointer on any other interface of the component. Interfaces are identified with a globally unique identifier (GUID) guaranteed to be unique in time and space. Since this function has to be on every interface, it has been abstracted into a specific interface called '''IUnknown''' which all other interfaces must inherit from.
The two other functions exposed by '''IUnknown''' are '''AddRef''' and '''Release'''. These functions should be called respectively when a client gets a reference on an interface or when it discards that reference. These two functions define the lifetime of the component: each interface keeps track of clients keeping a reference on them and when no clients have references anymore, the component can be unloaded from memory. You might start worrying thinking that this business of reference counting will imply lots of headaches, memory leaks, etc. and you would be right should you choose a low-level language to implement your components. Fortunately, you will never have to implement or use these functions in Eiffel: all the processing related to IUnknown is provided by the EiffelCOM runtime. Calls to '''QueryInterface''' are done "behind the scene" and only when needed. The lifetime of the component is also taken care of by the EiffelCOM runtime.
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard|EiffelCOM wizard]] <br/>
[[EiffelCOM Library| EiffelCOM library]] <br/>
[[EiffelCOM: Introduction| Introduction]] <br/>
[[Generalities|Generalities]] <br/>
[[Coclass| Coclasses]] <br/>
[[The Component Location| Component Location]] <br/>
[[Access Type| Access Type]] <br/>
[[Deeper into COM| Deeper into COM]] }}

24
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/com-and-eiffel/component-location.wiki Normal file
View File

@@ -0,0 +1,24 @@
[[Property:title|The Component Location]]
[[Property:weight|4]]
<div>
==Types of Components==
ActiveX, DirectX, OCX, COM+, ADO+, ASP etc. who never heard of these technologies? They all represent yet another use of the COM standard. This paragraph will focus on categorizing COM components according to their own properties as well as the context in which they are used. The categorization will define how the EiffelCOM wizard should be used to wrap or create a component. </div>The first criteria that defines the type of component is from where it will be accessed: will the component be loaded in the client process or will the component be a remote server for a distributed application? In the former case, the component is compiled as a Dynamic Link Libraries (DLL) while in the latter case it is a standard executable. <div>
==In-process Components==
Typical instances of DLL components are found in technologies such as OCX, ActiveX, or ASP. These are small, downloadable binaries that will be loaded and executed in a container. The container acts as a client of the component. The EiffelCOM wizard provides the ability to wrap such components by providing access to its interface to any Eiffel container. It is also possible to create a new In-process component in Eiffel.
One main difference with out-of-process components (other than the nature of the module, DLL versus executable) is the way in-process components are activated. In the case of out-of-process components, the component will specify COM when it is ready to receive calls from client. In the case of an in-process server the call is coming directly from COM: COM first loads the DLL into the client process and then calls the exported function DllGetClassObject to access the component class object. The other three exported functions of an in-process component are DllRegister to register the component in the Windows registry, DllUnregister to unregister the component from the registry and finally DllCanUnloadNow which gets called by COM whenever it tries to unload the component from memory. These four functions must be accessible from outside the DLL for the in-process component to work properly.
</div><div>
==Out-of-process Components==
These components are standard executable acting as servers that can be accessed locally or over a network. Typically used in a three tier client server architecture, the major difference with in-process servers (other than the module type - executable instead of DLL) is their lifetime. In-process components are typically loaded to achieve a specific task and unloaded just after while out-of-process components are servers supposed to run continuously. The EiffelCOM wizard allows to build clients for such servers in Eiffel. It also provides the ability to create such servers. </div>
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard|EiffelCOM wizard]] <br/>
[[EiffelCOM Library| EiffelCOM library]] <br/>
[[EiffelCOM: Introduction| Introduction]] <br/>
[[Generalities|Generalities]] <br/>
[[COM Interfaces| COM Interfaces]] <br/>
[[Coclass| Coclasses]] <br/>
[[Access Type| Access Type]] <br/>
[[Deeper into COM| Deeper into COM]] }}

21
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/com-and-eiffel/eiffelcom-introduction.wiki Normal file
View File

@@ -0,0 +1,21 @@
[[Property:title|EiffelCOM: Introduction]]
[[Property:weight|0]]
This chapter covers enough information about COM for Eiffel developers to use the EiffelCOM wizard in an effective way. It does not cover all of COM since it would require an entire book but presents the main concepts needed to understand how to build an EiffelCOM system.
Briefly said, the Component Object Model is a Microsoft binary standard that establishes how two binary units can access each other at runtime. Such binary units can run in the same process, in different processes on the same machine, or even on different machines. Components can be implemented in any language as long as the compiler produces COM standard compliant binaries.
The advantages of such an approach include an increased reusability (binary reuse), a better version management (COM standard implies that new component versions are compatible with the older ones) and a built-in runtime environment. The binary reuse aspect of COM added with the source reuse ability of Eiffel offer the developer an ideal platform to increase considerably their productivity.
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard|EiffelCOM wizard]] <br/>
[[EiffelCOM Library| EiffelCOM library]] <br/>
[[Generalities| Generalities]] <br/>
[[COM Interfaces| COM Interfaces]] <br/>
[[Coclass| Coclasses]] <br/>
[[The Component Location| Component Location]] <br/>
[[Access Type| Access Type]] <br/>
[[Deeper into COM| Deeper into COM]] }}

18
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/com-and-eiffel/index.wiki Normal file
View File

@@ -0,0 +1,18 @@
[[Property:title|EiffelCOM]]
[[Property:link_title|COM and Eiffel]]
[[Property:weight|-15]]
* [[EiffelCOM: Introduction|Introduction]]
* [[Generalities|Generalities]]
* [[COM Interfaces|Interfaces]]
* [[Coclass|Coclasses]]
* [[The Component Location|Component Location]]
* [[Access Type|Access Type]]
* [[Deeper into COM|Deeper into COM]]
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard|EiffelCOM wizard]] <br/>
[[EiffelCOM Library| EiffelCOM library]] }}

34
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-guided-tour/accessing-com-component.wiki Normal file
View File

@@ -0,0 +1,34 @@
[[Property:title|Accessing a COM component]]
[[Property:link_title|Accessing a COM Component]]
[[Property:weight|2]]
The third tutorial describes how to access a COM component. It will build a client of the <eiffel>StringManipulator</eiffel> component built in the first tutorial.
==Step by step instructions==
# In '''Project''', in the '''Current project''' input field, type in ''string_manipulator_client'' and press '''enter'''.
# In '''Project Type''', choose ''Access an existing COM component''.
# In '''Component Information''', click the browse button (the button with '''...''') and open the file ''$ISE_EIFFEL\examples\com\wizard\string_manipulator\string_manipulator.idl'' where ''$ISE_EIFFEL'' represents the path to the EiffelStudio installation directory.
# Click '''Next'''.
# In '''Component Type''', choose ''In-process (*.dll)''.
# In '''Generation Options''', click the browse button and select the directory where the project should be created (later referenced as ''destination folder''). Choose ''$ISE_EIFFEL\examples\com\wizard\string_manipulator\generated\client'' where ''$ISE_EIFFEL'' represents the path to the EiffelStudio directory.
# Make sure both '''Compile C code''' and '''Compile Eiffel code''' are checked.
# Select '''Overwrite existing files'''.
# Click '''Generate'''.
# Wait until the wizard is done.
==First look at the generated code==
At the end of the processing the '''EiffelStudio''' button becomes enabled. Click on it. This will automatically start EiffelStudio with the generated project so you can more easily navigate through the created Eiffel classes.
{{note| '''Note''': When accessing a COM component the EiffelCOM Wizard will generate a precompiled library which includes all the generated classes. This allows for easy browsing of the generated classes, however a precompilation project is read-only, so you need to start another EiffelStudio to reuse the generated classes. The interesting classes are all related to the coclass proxy <eiffel>STRING_MANIPULATOR_PROXY</eiffel>. The proxy is the Eiffel class that gives access to the component. Each feature on the proxy calls the corresponding interface function on the component. You can use the EiffelStudio opened by the wizard to browse through the generated classes and study the class hierarchy.}}
==Implementing a client==
To implement a client of the <eiffel>StringManipulator</eiffel> component open a new EiffelStudio. Create the project in ''$ISE_EIFFEL\examples\com\wizard\string_manipulator\client'' using the ecf file found in that directory. Freeze and run the project. You are now accessing the previously built component and calling functions on its interfaces! The class <eiffel>MY_STRING_MANIPULATOR</eiffel> inherits from the generated <eiffel>STRING_MANIPULATOR_PROXY</eiffel> and redefines the feature ''replace_substring_user_precondition''. The generated interfaces include contracts for each exposed function. You can redefine the ''user_precondition'' features to implement your own preconditions.
{{note| '''Note''': If a COM component should be added to an existing client, the generated ecf file can be added as a library. }}
==Contracts==
Contracts can be broken directly on the proxy in which case you will get a standard contract violation in the client. If contracts are broken on the server then the exception will be forwarded by the EiffelCOM runtime to the client. The feature replace_substring_user_precondition in <eiffel>MY_STRING_MANIPULATOR</eiffel> includes has some assertions.: Comment them out. Now the contract of the <code> [[ref:libraries/base/reference/string_8_chart|replace_substring]] </code> feature is wrong and erroneous calls can be made. Quick melt the changes and run the client. Enter some invalid numbers in the fields used to call this feature. After you click '''Replace''' you will see an error message box warning you that a precondition was violated on the server side. This demonstrates contracts `over the wire'. The precondition was violated in the server; this exception was caught by the EiffelCOM runtime and sent back to the client.
{{seealso| '''See Also''' <br/>
[[Creating a new COM component|Creating a new COM component]] <br/>
[[Creating a new component from an Eiffel project|Creating a new component from an Eiffel Project]] }}

44
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-guided-tour/creating-new-com-component.wiki Normal file
View File

@@ -0,0 +1,44 @@
[[Property:title|Creating a new COM component]]
[[Property:link_title|Creating a New COM Component]]
[[Property:weight|0]]
This first tutorial describes creating a COM component from a COM definition file that is either an IDL file or a Type Library. The tutorial focuses on creating an in-process (DLL) component, called <eiffel>StringManipulator</eiffel>. The component exposes one interface <eiffel>IString</eiffel> that includes the functions <eiffel>ReplaceSubstring</eiffel> and <eiffel>PruneAll</eiffel> corresponding respectively to the features <eiffel> [[ref:libraries/base/reference/string_8_chart|replace_substring]] </eiffel> and <eiffel> [[ref:libraries/base/reference/string_8_chart|prune_all]] </eiffel> of the class <eiffel> [[ref:libraries/base/reference/string_8_chart| <eiffel>STRING</eiffel> ]] </eiffel> from the EiffelBase library. <eiffel>IString</eiffel> also exposes the property <eiffel>String</eiffel> which represents the manipulated string. The property can be set or read.
==Step by step instructions==
# In '''Project''', in the '''Current project''' input field, type in ''string_manipulator_server'' and press '''enter'''.
# In '''Project Type''', choose ''Create a new COM component''.
# In '''Component Information''', click the browse button (the button with '''...''') and open the file ''$ISE_EIFFEL\examples\com\wizard\string_manipulator\string_manipulator.idl'' where ''$ISE_EIFFEL'' represents the path to the EiffelStudio installation directory.
# Make sure '''Generate and use marshaller DLL''' is not checked.
# Click '''Next'''.
# In '''Component Type''', choose ''In-process (*.dll)''.
# In '''Generation Options''', click the browse button and select the directory where the project should be created (later referenced as ''destination folder''). Choose ''$ISE_EIFFEL\examples\com\wizard\string_manipulator\generated\component'' where ''$ISE_EIFFEL'' represents the path to the EiffelStudio directory.
# Make sure both '''Compile C code''' and '''Compile Eiffel code''' are checked.
# Make sure '''Clean destination folder prior to generation''' is selected.
# Click '''Generate'''.
# Wait until the wizard is done.
==First look at the generated code==
At the end of the processing the '''EiffelStudio''' button becomes enabled. Click on it. This will automatically start EiffelStudio with the generated project so you can more easily navigate through the created Eiffel classes. You can save the processing output by clicking the '''Save''' button.
The deferred class <eiffel>STRING_MANIPULATOR_COCLASS</eiffel> represents the component and exposes all its functionality. It inherits from <eiffel>ISTRING_INTERFACE</eiffel> which corresponds to the '''IString''' interface and has one heir <eiffel>STRING_MANIPULATOR_COCLASS_IMP</eiffel> which implements all the deferred features. The default implementation in the heir is empty.
==Implementing the component==
To do something more interesting than merely returning an error to the client edit the implementation of the <eiffel>STRING_MANIPULATOR_COCLASS_IMP</eiffel> class. There is an implementation of the class in ''$ISE_EIFFEL\examples\com\wizard\string_manipulator\server''\. Copy this file over to ''$ISE_EIFFEL\examples\com\wizard\string_manipulator\generated\component\server\component'' and freeze the project. Voila!, you have your first EiffelCOM component up and running.
==Running the component==
The component needs to be registered prior to being loaded. Register an out-of-process component using the following syntax:
<code>
system_name.exe -Regserver</code>
where ''system_name'' is the name of the component executable file. Register an in-process component using the ''regsvr32'' utility using the following syntax:
<code>
regsvr32 system_name.dll</code>
where ''system_name'' is the name of the dll (e.g. string_manipulator). So to register the <eiffel> StringManipulator</eiffel> component, run:
<code>
cd $ISE_EIFFEL\examples\com\wizard\string_manipulator\generated\component\server\EIFGENs\default\W_code
regsvr32 string_manipulator.dll</code>
Once registered, follow the steps described in [[Accessing a COM component|Accessing a COM component]] to build the component's client.
{{seealso| '''See Also''' <br/>
[[Creating a new component from an Eiffel project|Creating a new component from an Eiffel Project]] <br/>
[[Accessing a COM component|Accessing a COM component.]] }}

43
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-guided-tour/creating-new-component-eiffel-project.wiki Normal file
View File

@@ -0,0 +1,43 @@
[[Property:title|Creating a new component from an Eiffel project]]
[[Property:weight|1]]
The second tutorial describes creating a COM component from an Eiffel system. The tutorial example <eiffel>String</eiffel> is almost identical to <eiffel>StringManipulator</eiffel> of the previous tutorial. In the <eiffel>StringManipulator</eiffel> example the wizard starts from an IDL file and builds an Eiffel System; in contrast, the <eiffel>String</eiffel> example takes an Eiffel system and generates an IDL file and the required plumbing code to make the Eiffel project accessible to COM.
==Step by step instructions==
# Create a new Eiffel project in the directory ''$ISE_EIFFEL\examples\com\wizard\e2idl\eproject'' where $ISE_EIFFEL represents the path to the EiffelStudio installation directory.
# Select the ECF file located in the same directory and compile.
# Start the EiffelCOM Wizard
# In '''Project''', in the '''Current project''' input field, type in ''string'' and press '''enter'''.
# In '''Project Type''', choose ''Add a COM interface to an existing Eiffel project''.
# In the field under '''Path to Eiffel project location''' enter ''$ISE_EIFFEL\examples\com\wizard\e2idl\eproject''.
# Click the browse button under '''Path to system's configuration file (*.ecf)''' and open the file ''$ISE_EIFFEL\examples\com\wizard\e2idl\eproject\string.ecf''.
# In the text field under '''Target to use''', enter: ''string''.
# In the text field under '''Name of Eiffel facade class''', enter: <eiffel>string_manipulator</eiffel>.
# In the text field under '''Name of Eiffel facade class cluster''', enter: <eiffel>root_cluster</eiffel>.
# Click '''Next'''.
# In '''Component Type''', choose ''In-process (*.dll)''.
# In '''Generation Options''', click the browse button and select the directory where the project should be created. Choose ''$ISE_EIFFEL\examples\com\wizard\e2idl\generated''.
# Make sure both '''Compile C code''' and '''Compile Eiffel code''' are checked.
# Make sure '''Clean destination folder prior to generation''' is selected.
# Click '''Generate'''.
# Wait until the wizard is done.
==First look at the generated code==
The generated Eiffel classes include:
* <eiffel>ISTRING_MANIPULATOR_INTERFACE</eiffel>: This class represents the only interface exposed by the COM component.
* <eiffel>STRING_MANIPULATOR_PROXY_IMP</eiffel>: This class implements the coclass, it inherits from the interface and implements its members.
* <eiffel>ECOM_STRING_REGISTRATION</eiffel>: This class contains the code required to register the component.
You do not need to modify or implement any classes. The wizard produces a ready-to-use component.
{{tip| '''Tip''': <br/>
In most Eiffel systems functionality is spread out throughout the system. No single class exposes the full functionality of the system and can serve as a Facade to the outside world. Running the wizard on any such class would not be practical. Before starting the wizard write an Eiffel class that acts as a Facade and forwards client calls to the appropriate subsystems. Enter the Facade class name into '''Name of Eiffel facade class''' field. The wizard generates an IDL file from this class. }}
{{seealso| '''See Also''' <br/>
[[Creating a new COM component|Creating a new COM component]] <br/>
[[Accessing a COM component|Accessing a COM component.]] }}

15
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-guided-tour/index.wiki Normal file
View File

@@ -0,0 +1,15 @@
[[Property:title|EiffelCOM Wizard Guided Tour]]
[[Property:weight|-13]]
This chapter explains how to use the EiffelCOM wizard to create COM components and to access existing components. <br/>
* [[Creating a new COM component|Creating a new COM component]] .
* [[Creating a new component from an Eiffel project|Creating a new component from an Eiffel Project.]]
* [[Accessing a COM component|Accessing a COM component.]]
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard Introduction|Introduction]] <br/>
[[EiffelCOM Wizard Reference|EiffelCOM wizard reference]] }}

19
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-introduction.wiki Normal file
View File

@@ -0,0 +1,19 @@
[[Property:title|EiffelCOM Wizard Introduction]]
[[Property:weight|-14]]
The COM standard allows software components written in different languages to communicate with each other. However, building COM compliant applications requires the development of a large amount of code only dedicated to supporting the technology. The EiffelCOM wizard was designed to free Eiffel developers from having to write the plumbing code.
The EiffelCOM wizard is a powerful tool that enables the fast development of COM components in Eiffel and accessing COM components from Eiffel systems. It consists of a series of input fields, which ask about the component's characteristics. The wizard needs the data to produce an Eiffel system skeleton, the code to access or create a component, and the component-specific runtime libraries.
The wizard allows Eiffel developers with little COM knowledge to develop and reuse COM components. The design of the generated code follows the Eiffel standards and will be familiar to experienced Eiffel users. The only prerequisite to use the EiffelCOM wizard is an understanding of the '''Interface Definition Language'''. '''IDL''' describes a component. Compilers can generate '''Type Libraries''' from IDL files. Tools that need information on a given component, such as the EiffelCOM wizard, Visual Basic, etc. will analyze the Type Libraries. The IDL syntax is very close to C so should be easy to learn for developers that are familiar with this language.
The wizard generates code from a Type Library and additional information given by the user. The generated code consists of Eiffel classes, C/C++ files, and library files. The wizard automatically produces library files from generated C and C++ code. You do not need to modify generated C/C++ code to build your EiffelCOM system.
==Code Generation Process==
[[Image:introduction]]
The wizard can automatically compile the generated C and Eiffel code. To produce a Type Library corresponding to a given IDL file the wizard relies on '''MIDL''', the Microsoft IDL compiler. You may also provide the wizard with a Type Library directly. The wizard can also be used to add a COM interface to an existing Eiffel project. For the rest of the manual a '''COM Definition File''' will refer to the input file given to the wizard (either an IDL file, a Type Library or an Eiffel project file).
{{seealso| '''See Also''': [[EiffelCOM Wizard Guided Tour|Guided Tour]] , [[EiffelCOM Wizard Reference|EiffelCOM wizard reference]] }}

70
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-reference/building-com-component.wiki Normal file
View File

@@ -0,0 +1,70 @@
[[Property:title|Building a COM Component]]
[[Property:weight|5]]
The EiffelCOM wizard allows for the development of both in-process (DLLs) and out-of-process (EXEs) COM components in Eiffel.
==Using the Generated Code==
If the project consists of adding a COM interface to an existing Eiffel project then the wizard will generate (and optionally compile) everything required to implement the COM component. No extra work is required.
If the project uses a COM definition file (either an IDL file or a type library), the EiffelCOM Wizard generates empty features in the classes corresponding to the component's coclasses. The implementation can then be added into these empty features.
{{warning| '''Warning''': Depending on the project settings, the EiffelCOM Wizard may overwrite the files containing the classes corresponding to the component's colasses if the project is re-generated thereby replacing the implemented features with empty ones. Make sure the destination folder is different from the folder where the classes have been implemented prior to re-generating the project. }}
Unlike the code generated to access an existing component, the code generated to implement a new COM component will differ for an in-process or an out-of-process component. The difference lies in the component activation code in the class <eiffel>ECOM_<Name_of_system>_REGISTRATION</eiffel>. If the component is in-process then this class includes the four functions that need to be exported from an in-process COM component ( <eiffel>DllRegisterServer</eiffel>, <eiffel>DllUnregisterServer</eiffel>, <eiffel>DllGetClassObject</eiffel>, and <eiffel>DllCanUnloadNow</eiffel>). If the component is out-of-process then the registration class includes a feature initializing the component and its graphical user interface.
The architecture of the generated code is similar to the one used by the code generated to access an existing component: classes corresponding to the component's coclasses inherit from classes corresponding to the component's interfaces and implement all the deferred features. There is however a major difference: the classes corresponding to the component's coclasses should '''not''' be inherited from. Instead their implementation should be completed. Putting the implementation in a heir class would cause a runtime failure since the EiffelCOM generated code will instantiate the class corresponding to the component's coclass when being called rather than any descendant that would actually contain the implementation. The classes corresponding to the component's coclasses are all suffixed with <eiffel>_COCLASS_IMP</eiffel>.
==Component's GUI==
In the case of an out-of-process server, the component might need a Graphical User Interface. There are two different scenarios in which the component can be activated: either its user launched it explicitly (e.g. by double clicking the executable icon) or it was launched by the COM runtime to satisfy a client request. In some cases it might be required for the component to have a different behavior in these two cases (for example the GUI could only be necessary when the component was launched explicitly by the user but should be hidden when launched by the COM runtime). The generated registration class for an out-of-process server includes the feature:
<code>
main_window: WEL_FRAME_WINDOW</code>
This feature is a <code>once</code> function that can return the class corresponding to the component window. By default, this window is displayed only if COM does not start the component. When COM loads an out-of-process component, it appends the command line parameter "-embedding" to the executable. The generated registration class looks for this option and if it is part of the process argument list then it sets the default window appearance to hidden. Of course this default implementation may be modified if needed.
==Exceptions==
The COM standard specifies that each COM routine should return a status code to the client. The status code is encoded in a <eiffel>HRESULT</eiffel> value. Such behavior goes against the Command Query Separation Principle in Eiffel. The EiffelCOM generated system should use exceptions instead of returning <eiffel>HRESULT</eiffel> values to the client. By default the EiffelCOM runtime will always return <eiffel>S_OK</eiffel> meaning that the routine succeeded. To notify the client of a problem (e.g. invalid argument value), the EiffelCOM component should raise the corresponding exception from class <eiffel>ECOM_EXCEPTION</eiffel> using the feature <eiffel>trigger</eiffel> from the same class. The EiffelCOM runtime will catch the exception and send the corresponding <eiffel>HRESULT</eiffel> back to the client. Here is what the Eiffel code for a COM component should look like:
<code>
indexing
description: "Eiffel coclass server example"
class
ECOM_SERVER_COCLASS_IMP
inherit
ECOM_SERVER_COCLASS -- Generated by the wizard
ECOM_EXCEPTION
export
{NONE} all
end
feature -- Basic Operations
coclass_feature (an_argument: ARGUMENT_TYPE) is
-- Example of a coclass feature
do
if not is_valid (an_argument) then
trigger (E_invalidargument)
else
-- Normal processing
end
end
feature {NONE} -- Implementation
is_valid (an_argument: ARGUMENT_TYPE): BOOLEAN is
-- Is an_argument a valid argument?
do
-- Test of validity of an_argument
end
end -- class ECOM_SERVER_COCLASS_IMP</code>
This class inherits from the generated Eiffel coclass and from <eiffel>ECOM_EXCEPTION</eiffel>. It redefines the feature <eiffel>coclass_feature</eiffel> from the generated coclass. This feature is part of the interface functions that can be called by clients of the component. Its implementation uses the feature<eiffel>trigger</eiffel> from <eiffel>ECOM_EXCEPTION</eiffel> to raise exceptions in case the feature cannot be executed normally (invalid argument). The EiffelCOM runtime catches the exception and maps it into an <eiffel>HRESULT</eiffel> that is sent back to the client.
{{seealso| '''See Also''': [[How the EiffelCOM Wizard works|How the EiffelCOM Wizard Works]] , [[Generated Files|Generated Files]] , [[Class Hierarchy|Class Hierarchy]] , [[Eiffel Project Processing|Adding a COM Interface to an Eiffel Project]] , [[Reusing a COM Component|Accessing a COM Component]] , [[Wizards: Command Line Options|Command Line Options]] }}

17
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-reference/class-hierarchy.wiki Normal file
View File

@@ -0,0 +1,17 @@
[[Property:title|Class Hierarchy]]
[[Property:weight|2]]
The generated Eiffel code reflects the architecture of the component described in the definition file. Each interface corresponds to a deferred Eiffel class that includes one deferred feature per interface function. The deferred features are implemented in heirs of the interface class. Classes inheriting from these interfaces implement either a coclass or an implemented interface (that is an interface whose instance might be used as an argument on one of the component interfaces functions).
[[Image:interface-inheritance]]
In a project accessing an existing component, the Eiffel classes corresponding to component coclasses inherit from the class [[ref:libraries/com/reference/ecom_queriable_chart| <eiffel>ECOM_QUERIABLE</eiffel> ]] , which is part of the EiffelCOM library. This class includes the feature <eiffel>make_from_other</eiffel> which allows initializing the component from another instance of [[ref:libraries/com/reference/ecom_interface_chart| <eiffel>ECOM_INTERFACE</eiffel> ]] .
[[Image:interface-inheritance-server]]
In a project implementing a new component, the Eiffel classes corresponding to component coclasses inherit from the class [[ref:libraries/com/reference/ecom_stub_chart| <eiffel>ECOM_STUB</eiffel> ]] , which is part of the EiffelCOM library. This class includes the feature [[ref:libraries/com/reference/ecom_stub_chart]] which allows initializing the component.
The '''Interface_proxy''' folder includes Eiffel classes wrapping interfaces that may be returned by functions on other interfaces. These classes inherit from both the deferred interface class located in '''Common\Interfaces''' and [[ref:libraries/com/reference/ecom_queriable_chart| <eiffel>ECOM_QUERIABLE</eiffel> ]] .
[[Image:implemented-interface]]
The '''Interface_stub''' folder includes Eiffel classes implementing interfaces that may be given to the component as an argument. These classes inherit from both the deferred interface class and [[ref:libraries/com/reference/ecom_stub_chart| <eiffel>ECOM_STUB</eiffel> ]] .
[[Image:implemented-interface-server]]
{{seealso| '''See Also''': [[How the EiffelCOM Wizard works|How the EiffelCOM Wizard Works]] , [[Generated Files|Generated Files]] , [[Eiffel Project Processing|Adding a COM Interface to an Eiffel Project]] , [[Reusing a COM Component|Accessing a COM Component]] , [[Building a COM Component|Building a COM Component]] , [[Wizards: Command Line Options|Command Line Options]] }}

19
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-reference/eiffel-project-processing.wiki Normal file
View File

@@ -0,0 +1,19 @@
[[Property:title|Eiffel Project Processing]]
[[Property:weight|3]]
The EiffelCOM Wizard can be used to add a COM interface to an existing Eiffel project. The advantage of that approach is that it doesn't require any knowledge about IDL. The EiffelCOM Wizard will take care of generating the IDL from the Eiffel facade class. The generated IDL will define one coclass containing one interface that corresponds to the contract view of the facade class.
==Designing the Facade Class==
The facade class should be designed so that it exposes the functionality of the Eiffel system that needs to be accessed from clients of the component. Only the public routines will be exported to the IDL and thus to clients (the class should not have any public attributes, see the list of requirements below).
There are some rules that the facade class must follow for the COM wizard to be able to generate correct IDL:
* The facade class must have a creation procedure called <eiffel>make</eiffel> that does not take any argument. This is the procedure that will be called by the EiffelCOM runtime to initialize the Eiffel object when a COM call arrives from a client.
* The arguments and objects returned by the public routines of the facade class must be of one of the following types: [[ref:libraries/base/reference/character_8_chart| <eiffel>CHARACTER_8</eiffel> ]] , [[ref:libraries/base/reference/integer_32_chart| <eiffel>INTEGER_32</eiffel> ]] , [[ref:libraries/base/reference/real_32_chart| <eiffel>REAL_32</eiffel> ]] , [[ref:libraries/base/reference/real_64_chart| <eiffel>REAL_64</eiffel> ]] , [[ref:libraries/base/reference/boolean_chart| <eiffel>BOOLEAN</eiffel> ]] , [[ref:libraries/base/reference/integer_32_ref_chart| <eiffel>INTEGER_32_REF</eiffel> ]] , [[ref:libraries/base/reference/boolean_ref_chart| <eiffel>BOOLEAN_REF</eiffel> ]] , [[ref:libraries/base/reference/real_32_ref_chart| <eiffel>REAL_32_REF</eiffel> ]] , [[ref:libraries/base/reference/character_8_ref_chart| <eiffel>CHARACTER_8_REF</eiffel> ]] , [[ref:libraries/base/reference/real_64_ref_chart| <eiffel>REAL_64_REF</eiffel> ]] , [[ref:libraries/base/reference/string_8_chart| <eiffel>STRING_8</eiffel> ]] , [[ref:libraries/com/reference/ecom_currency_chart| <eiffel>ECOM_CURRENCY</eiffel> ]] , [[ref:libraries/com/reference/ecom_decimal_chart| <eiffel>ECOM_DECIMAL</eiffel> ]] , [[ref:libraries/com/reference/ecom_interface_chart]] , or [[ref:libraries/com/reference/ecom_array_chart]] . Features with arguments or return objects that are of a type not in this list are excluded from the generated IDL file and are not accessible to clients.
* The facade class should not contain any public attribute, only routines can be exported to COM clients.
* The facade class must belong to a successfully compiled Eiffel project.
{{seealso| '''See Also''': [[How the EiffelCOM Wizard works|How the EiffelCOM Wizard Works]] , [[Generated Files|Generated Files]] , [[Class Hierarchy|Class Hierarchy]] , [[Eiffel Project Processing|Adding a COM Interface to an Eiffel Project]] , [[Accessing a COM component|Accessing a COM Component]] , [[Reusing a COM Component|Reusing a COM Component]] , [[Wizards: Command Line Options|Command Line Options]] }}

14
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-reference/generated-files.wiki Normal file
View File

@@ -0,0 +1,14 @@
[[Property:title|Generated Files]]
[[Property:weight|1]]
The EiffelCOM Wizard generates code into the specified destination folder. The file hierarchy is the following:
[[Image:folders]]
* The '''Client''' folder includes all the files used to access a COM component. The subfolders '''Clib''' and '''Include''' contain respectively the C++ source files and header files. The subfolder '''Component''' contains the Eiffel classes corresponding to the component's coclasses. Finally the subfolder '''Interface_proxy''' contains classes wrapping interfaces that may be returned by functions of the component. These classes may be of interest for systems implementing a new COM component as well. The '''Client''' folder also contains a ECF file that can be used to precompile the generated Eiffel classes if the project consists of accessing an existing component. It is also possible to directly use the ECF file as a library in an existing project.
* The '''Common''' folder includes classes that are useful both when accessing and implementing a COM component. It includes the usual C++ folders as well as the '''Interfaces''' and '''Structures''' folders. The '''Interfaces''' folder contains Eiffel classes corresponding to COM interfaces. These are deferred classes that only define the signature of the COM interfaces members. The '''Structures''' folder contains Eiffel classes wrapping any structure defined in the COM definition file (IDL or type library).
* Optionally, the EiffelCOM Wizard may generate a '''idl''' folder which contains the IDL file generated from the Eiffel facade class if the project consists of adding a COM interface to an existing Eiffel project.
* The '''Server''' folder includes files used to implement a COM component. Apart from the usual C++ folders, it also includes a '''Component''' folder which contains Eiffel classes corresponding to the component's coclasses and a '''Interface_stub''' folder which contains Eiffel classes wrapping interfaces that may be given as argument to the component. This last folder may also be useful when accessing a COM component. The '''Server''' folder also includes a ECF file which can be used to compile the generated system if the project consists of creating a new component.
{{seealso| '''See Also''': [[How the EiffelCOM Wizard works|How the EiffelCOM Wizard Works]] , [[Class Hierarchy|Class Hierarchy]] , [[Eiffel Project Processing|Adding a COM Interface to an Eiffel Project]] , [[Reusing a COM Component|Accessing a COM Component]] , [[Building a COM Component|Building a COM Component]] , [[Wizards: Command Line Options|Command Line Options]] }}

19
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-reference/how-eiffelcom-wizard-works.wiki Normal file
View File

@@ -0,0 +1,19 @@
[[Property:title|How the EiffelCOM Wizard works]]
[[Property:weight|0]]
Depending on the project settings there are between 2 and 6 major steps involved when generating the Eiffel system:
* '''IDL Generation''': If the project consists of adding a COM interface to an existing Eiffel project, the first step accomplished by the EiffelCOM Wizard consists of generating an IDL file from the specified facade class (see [[Eiffel Project Processing|Adding a COM interface to an Eiffel project]] for additional details).
* '''IDL Compilation''': If the project uses an IDL file (whether it was specified or the result of processing a facade class from an existing Eiffel project), the EiffelCOM Wizard then compiles it into a type library.
* '''Type Library Parsing''': The EiffelCOM Wizard then analyzes the type library (whether it was specified in the settings or is the result of an IDL file compilation) and stores the information it needs to generate the code into an internal representation.
* '''Code Generation''': The EiffelCOM wizard generates both the Eiffel and C/C++ code from the information gathered during the previous step (see [[Generated Files|Generated Files]] for a list of generated files)
* '''C/C++ Compilation''': If specified in the project settings, the EiffelCOM Wizard then compiles the generated C and C++ code into object files and libraries that will be linked into the Eiffel system.
* '''Eiffel Compilation''': If the project consists of accessing an existing component then the EiffelCOM Wizard compiles the generated Eiffel code into a precompiled library that contains all the generated classes. If the project consists of creating a new component then the EiffelCOM Wizard compiles the generated Eiffel code into a standard project using the registration class as root class.
Optionally, EiffelStudio can be opened on the generated system by clicking the corresponding button after the system has been compiled.
{{note| '''Note''': The EiffelStudio button will only be enabled if the Eiffel code was compiled. }}
{{seealso| '''See Also''': [[Generated Files|Generated Files]] , [[Class Hierarchy|Class Hierarchy]] , [[Eiffel Project Processing|Adding a COM Interface to an Eiffel Project]] , [[Reusing a COM Component|Accessing a COM Component]] , [[Building a COM Component|Building a COM Component]] , [[Wizards: Command Line Options|Command Line Options]] }}

18
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-reference/index.wiki Normal file
View File

@@ -0,0 +1,18 @@
[[Property:title|EiffelCOM Wizard Reference]]
[[Property:weight|-12]]
The EiffelCOM Wizard allows the creation of Eiffel projects implementing or reusing COM components.
* [[How the EiffelCOM Wizard works|How the EiffelCOM Wizard works]] describes the steps followed by the wizard when creating the Eiffel project.
* [[Generated Files|Generated Files]] describes the list of generated files and their usage.
* [[Class Hierarchy|Class Hierarchy]] describes the class hierarchy of the generated Eiffel project.
* [[Eiffel Project Processing|Eiffel Project Processing]] covers how to add a COM interface to an existing EiffelStudio project.
* [[Reusing a COM Component|Accessing a COM Component]] describes how to reuse an existing COM component.
* [[Building a COM Component|Building a COM Component]] describes how to build a new COM component.
* [[Wizards: Command Line Options|Command Line Options]] describes using the wizard from the command line.
{{seealso| '''See Also''' <br/>
[[EiffelCOM Wizard Introduction|Introduction]] <br/>
[[EiffelCOM Wizard Guided Tour|Guided Tour]] }}

93
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-reference/reusing-com-component.wiki Normal file
View File

@@ -0,0 +1,93 @@
[[Property:title|Reusing a COM Component]]
[[Property:weight|4]]
The wizard generates the necessary code to access the existing component. The plumbing is already done so that instantiating an Eiffel class corresponding to one of the component's coclasses automatically calls the right COM initialization APIs.
==Using the Generated Code==
Calling a feature on an Eiffel class corresponding to one of the component's coclasses forwards the call to the member on the corresponding interface. The data types of the function arguments are either Eiffel types defined in Eiffel data structure libraries, standard data types defined in the EiffelCOM library, or custom data types declared in the COM definition file. For example, from the following IDL line:
<code>
HRESULT Function ([in] int a, [out, retval] MyStruct * b)</code>
The wizard generates the following feature:
<code>
function (a: INTEGER): MY_STRUCT_RECORD</code>
where <eiffel>MY_STRUCT_RECORD</eiffel> is a generated Eiffel wrapper around the IDL defined structure <eiffel>MyStruct</eiffel>. Structures represent one case of custom data types, interfaces represent another so for the following IDL:
<code>
HRESULT Function ([in] ISomething * pInterface)</code>
The wizard generates the following Eiffel feature:
<code>
function (p_interface: ISOMETHING_INTERFACE)</code>
where <eiffel>ISOMETHING_INTERFACE</eiffel> is a generated deferred class corresponding to the <eiffel>ISomething</eiffel> interface. Calling <eiffel>function</eiffel> requires passing an instance of a type that implements <eiffel>ISOMETHING_INTERFACE</eiffel>. The '''stubs''' implementing such interfaces can be found in '''Server\Interfaces_stub'''. In our example the Eiffel class would be named <eiffel>ISOMETHING_INTERFACE_IMPL_STUB</eiffel>. The default implementation of the stub is empty and should be completed to implement the wanted behavior. This is how callbacks can be implemented using EiffelCOM.
==Contracts==
All the Eiffel classes corresponding to the component's interfaces are generated in '''Common\Interfaces'''. These deferred classes include one deferred feature per function defined on the interface. They are equipped with automatically generated assertions. However, the wizard cannot generate fully specified contracts since it has no domain specific knowledge. It can only generate contracts that are domain independent. Such contracts, although useful, are not enough to describe entirely the behavior of the component. Generated contracts include checking for <eiffel>Void</eiffel> Eiffel objects as well as <code>null</code> C pointers for wrappers. There might be a need for additional assertions. Invariants and postconditions can be added in an heir of the generated Eiffel coclass proxy. Preconditions, however, cannot be strengthened. A workaround provided by the wizard consists of generating a precondition function for each feature in the interface. The default implementation of these functions always returns <eiffel>True</eiffel>. They can be redefined to implement the correct behavior:
<code>
function (a: INTEGER): MY_STRUCT is
-- Example of a generated Eiffel coclass feature
require
function_user_precondition: function_user_precondition
do
...
ensure
non_void_my_struct: Result /= Void
end</code>
So the complete class hierarchy for an Eiffel client coclass is the following:
[[Image:client-inheritance]]
==Exceptions==
The COM standard requires that any interface function returns a status value (known as a <eiffel>HRESULT</eiffel>). This means that any function which adheres to the COM standard actually corresponds to a side effect feature which the Eiffel methodology tries to avoid according to the ''Command Query Separation Principle''. The workaround used in EiffelCOM systems consists in mapping these return values to Eiffel exceptions. So if the component returns an <eiffel>HRESULT</eiffel> corresponding to an error code, the EiffelCOM runtime raises an Eiffel exception that needs to be caught by the client.
[[Image:exception-raising]]
As a result, any feature in the client making calls to the Eiffel classes corresponding to the component's coclasses should include a <code>rescue</code> clause. The processing done in this clause might depend on the nature of the exception. All the standard COM exceptions can be found in the library class <eiffel>ECOM_EXCEPTION_CODES</eiffel>, which is inherited from by <eiffel>ECOM_EXCEPTION</eiffel>. The later also inherits from the kernel class <eiffel>EXCEPTIONS</eiffel> and can consequently be used by the coclass client to catch the exceptions.
The following code snippet illustrates how a client can process exceptions raised by a call to an Eiffel class representing a component's coclass:
<code>
indexing
description: "Eiffel coclass client example"
class
COCLASS_CLIENT
inherit
ECOM_EXCEPTION
export
{NONE} all
end
feature -- Basic Operations
coclass_feature_client is
-- Example of a coclass feature caller
local
retried: BOOLEAN
coclass: EIFFEL_COCLASS_PROXY
do
if not retried then
create coclass.make
coclass.coclass_feature -- Actual call
end
rescue
if hresult = E_notimpl then
-- Process non implemented function error.
retried := True
retry
elseif hresult = E_invalidarg then
-- Process invalid argument error.
retried := True
retry
else
-- Forward exception to caller.
end
end
end -- class COCLASS_CLIENT</code>
{{seealso| '''See Also''': [[How the EiffelCOM Wizard works|How the EiffelCOM Wizard Works]] , [[Generated Files|Generated Files]] , [[Class Hierarchy|Class Hierarchy]] , [[Eiffel Project Processing|Adding a COM Interface to an Eiffel Project]] , [[Building a COM Component|Reusing a COM Component]] , [[Wizards: Command Line Options|Command Line Options]] }}

33
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/eiffelcom-wizard-reference/wizards-command-line-options.wiki Normal file
View File

@@ -0,0 +1,33 @@
[[Property:title|Wizards: Command Line Options]]
[[Property:weight|6]]
The EiffelCOM Wizard can be used from the command line for example in batch scripts. The command line utility is <code>com_wizard.exe</code> and is located in <code>$ISE_EIFFEL\wizards\com</code>. Each command line option has both a long and a short name. The long names are all prefixed with <code>--</code> while the short names are all prefixed with <code>-</code>. Options that take an argument should have the argument directly following the option with a space or a <code>=</code> sign in between the option name and the argument as in:
<code>
--ace="mysystem.ecf"</code>
this option is equivalent to:
<code>
-a "mysystem.ecf"</code>
The list of options is the following:
* '''--client, -c''' <DEFINITION_FILE>: Build client to access COM component described by <DEFINITION_FILE>.
* '''--server, -s''' <DEFINITION_FILE>: Build new COM component as described by <DEFINITION_FILE>.
* '''--eiffel, -e''' <PROJECT_FILE>: Add COM interface to Eiffel project with project file (*.epr) <PROJECT_FILE>.
* '''--ace, -a''' <ECF_FILE>: Path to ecf file of Eiffel project to be added a COM interface. Use together with <code>'--eiffel'</code>.
* '''--facade, -f''' >FACADE_CLASS>: Name of facade class to generate IDL from. Use together with <code>'--eiffel'</code>.
* '''--cluster, -u''' >CLUSTER>: Name of facade class cluster. Use together with <code>'--eiffel'</code>.
* '''--outofprocess, -o''': Access or build out of process component. By default access or build in-process component (DLL).
* '''--compilec, -i''': Compile generated C code.
* '''--compileeiffel, -l''': Compile generated Eiffel code. Implies '--compilec'.
* '''--marshaller, -m''': Build marshaller DLL, can only be used with '--server' and if definition file is an IDL file.
* '''--destination, -d''' <DESTINATION>: Generate files in <DESTINATION> folder. By default files are generated in current folder.
* '''--cleanup, -p''': Cleanup destination folder prior to generation. This option cannot be used together with <code>'--backup'</code>.
* '''--backup, -b''': Backup overriden files by adding extension '.bac'. This option cannot be used together with <code>'--cleanup'</code>.
* '''--graphical, -g''': Launch GUI, all other options are ignored.
* '''--nologo, -n''': Do not display copyright information.
* '''--version, -v''': Print version information.
* '''--help, -h''': Display help on how to use the EiffelCOM Wizard command line utility.
{{seealso| '''See Also''': [[How the EiffelCOM Wizard works|How the EiffelCOM Wizard Works]] , [[Generated Files|Generated Files]] , [[Class Hierarchy|Class Hierarchy]] , [[Eiffel Project Processing|Adding a COM Interface to an Eiffel Project]] , [[Reusing a COM Component|Accessing a COM Component]] , [[Building a COM Component|Building a COM Component]] }}

18
documentation/current/platform-specifics/microsoft-windows/com/eiffelcom-wizard/index.wiki Normal file
View File

@@ -0,0 +1,18 @@
[[Property:title|EiffelCOM Wizard]]
[[Property:weight|4]]
Type: Wizard <br/>
Platform: Windows
See: <br/>
* [[EiffelCOM Wizard Introduction|Introduction]]
* [[EiffelCOM Wizard Guided Tour|Guided Tour]]
* [[EiffelCOM Wizard Reference|Reference]]
{{seealso| '''See Also''' <br/>
[[EiffelCOM|The Component Object Model]] <br/>
[[EiffelCOM Library|EiffelCOM library]] }}