Developer’s Guide Borland Delphi 7 for Windows PHẦN 10 potx

Creating simple COM servers 43-15 Marshaling data This is called late binding because the controller binds to the property or method at runtime rather than at compile time. Note When importing a type library, Delphi will query for dispIDs at the time it generates the code, thereby allowing generated wrapper classes to call Invoke without calling GetIDsOfNames. This can significantly increase the runtime performance of controllers. Custom interfaces Custom interfaces are user-defined interfaces that allow clients to invoke interface methods based on their order in the VTable and knowledge of the argument types. The VTable lists the addresses of all the properties and methods that are members of the object, including the member functions of the interfaces that it supports. If the object does not support IDispatch, the entries for the members of the object’s custom interfaces immediately follow the members of IUnknown. If the object has a type library, you can access the custom interface through its VTable layout, which you can get using the Type Library editor. If the object has a type library and also supports IDispatch, a client can also get the dispIDs of the IDispatch interface and bind directly to a VTable offset. Delphi’s type library importer (TLIBIMP) retrieves dispIDs at import time, so clients that use dispinterfaces can avoid calls to GetIDsOfNames; this information is already in the _TLB unit. However, clients still need to call Invoke. Marshaling data For out-of-process and remote servers, you must consider how COM marshals data outside the current process. You can provide marshaling: • Automatically, using the IDispatch interface. • Automatically, by creating a type library with your server and marking the interface with the OLE Automation flag. COM knows how to marshal all the Automation-compatible types in the type library and can set up the proxies and stubs for you. Some type restrictions apply to enable automatic marshaling. • Manually by implementing all the methods of the IMarshal interface. This is called custom marshaling. Note The first method (using IDispatch) is only available on Automation servers. The second method is automatically available on all objects that are created by wizards and which use a type library. 43-16 Developer’ s Guide Marshaling data Automation compatible types Function result and parameter types of the methods declared in dual and dispatch interfaces and interfaces that you mark as OLE Automation must be Automation- compatible types. The following types are OLE Automation-compatible: • The predefined valid types such as Smallint, Integer, Single, Double, WideString. For a complete list, see “Valid types” on page 41-12. • Enumeration types defined in a type library. OLE Automation-compatible enumeration types are stored as 32-bit values and are treated as values of type Integer for purposes of parameter passing. • Interface types defined in a type library that are OLE Automation safe, that is, derived from IDispatch and containing only OLE Automation compatible types. • Dispinterface types defined in a type library. • Any custom record type defined within the type library. • IFont, IStrings, and IPicture. Helper objects must be instantiated to map •an IFont to a TFont •an IStrings to a TStrings •an IPicture to a TPicture The ActiveX control and ActiveForm wizards create these helper objects automatically when needed. To use the helper objects, call the global routines, GetOleFont, GetOleStrings, GetOlePicture, respectively. Type restrictions for automatic marshaling For an interface to support automatic marshaling (also called Automation marshaling or type library marshaling), the following restrictions apply. When you edit your object using the type library editor, the editor enforces these restrictions: • Types must be compatible for cross-platform communication. For example, you cannot use data structures (other than implementing another property object), unsigned arguments, AnsiStrings, and so on. • String data types must be transferred as wide strings (BSTR). PChar and AnsiString cannot be marshaled safely. • All members of a dual interface must pass an HRESULT as the function’s return value. If the method is declared using the safecall calling convention, this condition is imposed automatically, with the declared return type converted to an output parameter. • Members of a dual interface that need to return other values should specify these parameters as var or out, indicating an output parameter that returns the value of the function. Creating simple COM servers 43-17 Registering a COM object Note One way to bypass the Automation types restrictions is to implement a separate IDispatch interface and a custom interface. By doing so, you can use the full range of possible argument types. This means that COM clients have the option of using the custom interface, which Automation controllers can still access. In this case, though, you must implement the marshaling code manually. Custom marshaling Typically, you use automatic marshaling in out-of-process and remote servers because it is easier—COM does the work for you. However, you may decide to provide custom marshaling if you think you can improve marshaling performance. When implementing your own custom marshaling, you must support the IMarshal interface. For more information, on this approach, see the Microsoft documentation. Registering a COM object You can register your server object as an in-process or an out-of-process server. For more information on the server types, see“In-process, out-of-process, and remote servers” on page 40-7. Note Before you remove a COM object from your system, you should unregister it. Registering an in-process server To register an in-process server (DLL or OCX), choose Run|Register ActiveX Server. To unregister an in-process server, choose Run|Unregister ActiveX Server. Registering an out-of-process server To register an out-of-process server, run the server with the /regserver command-line option. You can set command-line options with the Run|Parameters dialog box. You can also register the server by running it. To unregister an out-of-process server, run the server with the /unregserver command-line option. As an alternative, you can use the tregsvr command from the command line or run the regsvr32.exe from the operating system. Note If the COM server is intended for use under COM+, you should install it in a COM+ application rather than register it. (Installing the object in a COM+ application automatically takes care of registration.) For information on how to install an object in a COM+ application, see “Installing transactional objects” on page 46-26. 43-18 Developer’ s Guide Testing and debugging the application Testing and debugging the application To test and debug your COM server application, 1 Turn on debugging information using the Compiler tab on the Project|Options dialog box, if necessary. Also, turn on Integrated Debugging in the Tools| Debugger Options dialog. 2 For an in-process server, choose Run|Parameters, type the name of the Automation controller in the Host Application box, and choose OK. 3 Choose Run|Run. 4 Set breakpoints in the Automation server. 5 Use the Automation controller to interact with the Automation server. The Automation server pauses when the breakpoints are reached. Note As an alternate approach, if you are also writing the Automation controller, you can debug into an in-process server by enabling COM cross-process support. Use the General page of the Tools|Debugger Options dialog to enable cross-process support. Creating an Active Server Page 44-1 Chapter 44 Chapter44 Creating an Active Server Page If you are using the Microsoft Internet Information Server (IIS) environment to serve your Web pages, you can use Active Server Pages (ASP) to create dynamic Web- based client/server applications. Active Server Pages let you write a script that gets called every time the server loads the Web page. This script can, in turn, call on Automation objects to obtain information that it includes in a generated HTML page. For example, you can write a Delphi Automation server, such as one to create a bitmap or connect to a database, and use this control to access data that gets updated every time the server loads the Web page. On the client side, the ASP acts like a standard HTML document and can be viewed by users on any platform using any Web Browser. ASP applications are analogous to applications you write using Delphi’s Web broker technology. For more information about the Web broker technology, see Chapter 33, “Creating Internet server applications.” ASP differs, however, in the way it separates the UI design from the implementation of business rules or complex application logic. • The UI design is managed by the Active Server Page. This is essentially an HTML document, but it can include embedded script that calls on Active Server objects to supply it with content that reflects your business rules or application logic. • The application logic is encapsulated by Active Server objects that expose simple methods to the Active Server Page, supplying it with the content it needs. Note Although ASP provides the advantage of separating UI design from application logic, its performance is limited in scale. For Web sites that respond to extremely large numbers of clients, an approach based on the Web broker technology is recommended instead. The script in your Active Server Pages and the Automation objects you embed in an active server page can make use of the ASP intrinsics (built-in objects that provide information about the current application, HTTP messages from the browser, and so on). 44-2 Developer’ s Guide Creating an Active Server Object This chapter shows how to create an Active Server Object using the Delphi Active Server Object wizard. This special Automation control can then be called by an Active Server Page and supply it with content. Here are the steps for creating an Active Server Object: • Create an Active Server Object for the application. • Define the Active Server Object’s interface. • Register the Active Server Object. • Test and debug the application. Creating an Active Server Object An Active Server Object is an Automation object that has access to information about the entire ASP application and the HTTP messages it uses to communicate with browsers. It descends from TASPObject or TASPMTSObject (which is in turn a descendant of TAutoObject), and supports Automation protocols, exposing itself for other applications (or the script in the Active Server page) to use. You create an Active Server Object using the Active Server Object wizard. Your Active Server Object project can be either an executable (exe) or library (dll), depending on your needs. However, you should be aware of the drawbacks of using an out-of-process server. These drawbacks are discussed in “Creating ASPs for in- process or out-of-process servers” on page 44-7. To display the Active Server Object wizard: 1 Choose File|New|Other. 2 Select the tab labeled, ActiveX. 3 Double-click the Active Server Object icon. In the wizard, give your new Active Server Object a name, and specify the instancing and threading models you want to support. These details influence the way your object can be called. You must write the implementation so that it adheres to the model (for example, avoiding thread conflicts). The instancing and threading models involve the same choices that you make for other COM objects. For details, see “COM object instancing types” on page 43-6 and “COM object instancing types” on page 43-6. The thing that makes an Active Server Object unique is its ability to access information about the ASP application and the HTTP messages that pass between the Active Server page and client Web browsers. This information is accessed using the ASP intrinsics. In the wizard, you can specify how your object accesses these by setting the Active Server Type: • If you are working with IIS 3 or IIS 4, you use Page Level Event Methods. Under this model, your object implements the methods, OnStartPage and OnEndPage, which are called when the Active Server page loads and unloads. When your object is loaded, it automatically obtains an IScriptingContext interface, which it uses to access the ASP intrinsics. These interfaces are, in turn, surfaced as properties inherited from the base class (TASPObject). Creating an Active Server Page 44-3 Creating an Active Server Object • If you are working with IIS5 or later, you use the Object Context type. Under this model, your object fetches an IObjectContext interface, which it uses to access the ASP intrinsics. Again, these interfaces are surfaced as properties in the inherited base class (TASPMTSObject). One advantage of this latter approach is that your object has access to all of the other services available through IObjectContext. To access the IObjectContext interface, simply call GetObjectContext (defined in the mtx unit) as follows: ObjectContext := GetObjectContext; For more information about the services available through IObjectContext, see Chapter 46, “Creating MTS or COM+ objects.” You can tell the wizard to generate a simple ASP page to host your new Active Server Object. The generated page provides a minimal script (written in VBScript) that creates your Active Server Object based on its ProgID, and indicates where you can call its methods. This script calls Server.CreateObject to launch your Active Server Object. Note Although the generated test script uses VBScript, Active Server Pages also can be written using Jscript. When you exit the wizard, a new unit is added to the current project that contains the definition for the Active Server Object. In addition, the wizard adds a type library project and opens the Type Library editor. Now you can expose the properties and methods of the interface through the type library as described in “Defining a COM object’s interface” on page 43-9. As you write the implementation of your object’s properties and methods, you can take advantage of the ASP intrinsics (described below) to obtain information about the ASP application and the HTTP messages it uses to communicate with browsers. The Active Server Object, like any other Automation object, implements a dual interface, which supports both early (compile-time) binding through the VTable and late (runtime) binding through the IDispatch interface. For more information on dual interfaces, see “Dual interfaces” on page 43-13. Using the ASP intrinsics The ASP intrinsics are a set of COM objects supplied by ASP to the objects running in an Active Server Page. They let your Active Server Object access information that reflects the messages passing between your application and the Web browser, as well as a place to store information that is shared among Active Server Objects that belong to the same ASP application. To make these objects easy to access, the base class for your Active Server Object surfaces them as properties. For a complete understanding of these objects, see the Microsoft documentation. However, the following topics provide a brief overview. 44-4 Developer’ s Guide Creating an Active Server Object Application The Application object is accessed through an IApplicationObject interface. It represents the entire ASP application, which is defined as the set of all .asp files in a virtual directory and its subdirectories. The Application object can be shared by multiple clients, so it includes locking support that you should use to prevent thread conflicts. IApplicationObject includes the following: Request The Request object is accessed through an IRequest interface. It provides information about the HTTP request message that caused the Active Server Page to be opened. IRequest includes the following: Table 44.1 IApplicationObject interface members Property, Method, or Event Meaning Contents property Lists all the objects that were added to the application using script commands. This interface has two methods, Remove and RemoveAll, that you can use to delete one or all objects from the list. StaticObjects property Lists all the objects that were added to the application with the <OBJECT> tag. Lock method Prevents other clients from locking the Application object until you call Unlock. All clients should call Lock before accessing shared memory (such as the properties). Unlock method Releases the lock that was set using the Lock method. Application_OnEnd event Occurs when the application quits, after the Session_OnEnd event. The only intrinsics available are Application and Server. The event handler must be written in VBScript or JScript. Application_OnStart event Occurs before the new session is created (before Session_OnStart). The only intrinsics available are Application and Server. The event handler must be written in VBScript or JScript. Table 44.2 IRequest interface members Property, Method, or Event Meaning ClientCertificate property Indicates the values of all fields in the client certificate that is sent with the HTTP message. Cookies property Indicates the values of all Cookie headers on the HTTP message. Form property Indicates the values of form elements in the HTTP body. These can be accessed by name. QueryString property Indicates the values of all variables in the query string from the HTTP header. ServerVariables property Indicates the values of various environment variables. These variables represent most of the common HTTP header variables. Creating an Active Server Page 44-5 Creating an Active Server Object Response The Request object is accessed through an IResponse interface. It lets you specify information about the HTTP response message that is returned to the client browser. IResponse includes the following: TotalBytes property Indicates the number of bytes in the request body. This is an upper limit on the number of bytes returned by the BinaryRead method. BinaryRead method Retrieves the content of a Post message. Call the method, specifying the maximum number of bytes to read. The resulting content is returns as a Variant array of bytes. After calling BinaryRead, you can’t use the Form property. Table 44.3 IResponse interface members Property, Method, or Event Meaning Cookies property Determines the values of all Cookie headers on the HTTP message. Buffer property Indicates whether page output is buffered When page output is buffered, the server does not send a response to the client until all of the server scripts on the current page are processed. CacheControl property Determines whether proxy servers can cache the output in the response. Charset property Adds the name of the character set to the content type header. ContentType property Specifies the HTTP content type of the response message’s body. Expires property Specifies how long the response can be cached by a browser before it expires. ExpiresAbsolute property Specifies the date and time when the response expires. IsClientConnected property Indicates whether the client has disconnected from the server. Pics property Set the value for the pics-label field of the response header. Status property Indicates the status of the response. This is the value of an HTTP status header. AddHeader method Adds an HTTP header with a specified name and value. AppendToLog method Adds a string to the end of the Web server log entry for this request. BinaryWrite method Writes raw (uninterpreted) information to the body of the response message. Clear method Erases any buffered HTML output. End method Stops processing the .asp file and returns the current result. Flush method Sends any buffered output immediately. Redirect method Sends a redirect response message, redirecting the client browser to a different URL. Write method Writes a variable to the current HTTP output as a string. Table 44.2 IRequest interface members (continued) Property, Method, or Event Meaning 44-6 Developer’ s Guide Creating an Active Server Object Session The Session object is accessed through the ISessionObject interface. It allows you to store variables that persist for the duration of a client’s interaction with the ASP application. That is, these variables are not freed when the client moves from page to page within the ASP application, but only when the client exits the application altogether. ISessionObject includes the following: Server The Server object is accessed through an IServer interface. It provides various utilities for writing your ASP application. IServer includes the following: Table 44.4 ISessionObject interface members Property, Method, or Event Meaning Contents property Lists all the objects that were added to the session using the <OBJECT> tag. You can access any variable in the list by name, or call the Contents object’s Remove or RemoveAll method to delete values. StaticObjects property Lists all the objects that were added to the session with the <OBJECT> tag. CodePage property Specifies the code page to use for symbol mapping. Different locales may use different code pages. LCID property Specifies the locale identifier to use for interpreting string content. SessionID property Indicates the session identifier for the current client. TimeOut property Specifies the time, in minutes, that the session persists without a request (or refresh) from the client until the application terminates. Abandon method Destroys the session and releases its resources. Session_OnEnd event Occurs when the session is abandoned or times out. The only intrinsics available are Application, Server, and Session. The event handler must be written in VBScript or JScript. Session_OnStart event Occurs when the server creates a new session is created (after Application_OnStart but before running the script on the Active Server Page). All intrinsics are available. The event handler must be written in VBScript or JScript. Table 44.5 IServer interface members Property, Method, or Event Meaning ScriptTimeOut property Same as the TimeOut property on the Session object. CreateObject method Instantiates a specified Active Server Object. Execute method Executes the script in a specified .asp file. GetLastError method Returns an ASPError object that describes the error condition. [...]... applications 7 Deploy the ActiveX control on the Web (optional) To create a new Active Form, perform the following steps: 1 Use the ActiveForm wizard to create an Active Form, which appears as a blank form in the IDE, and an associated ActiveX wrapper for that form 2 Use the form designer to add components to your Active Form and implement its behavior in the same way you create and implement an ordinary form... for any additional files and packages Creating an ActiveX control 45- 17 45-18 Developer’s Guide Chapter 46 Creating MTS or COM+ objects Chapter46 Delphi uses the term transactional objects to refer to objects that take advantage of the transaction services, security, and resource management supplied by Microsoft Transaction Server (MTS) (for versions of Windows prior to Windows 2000) or COM+ (for Windows. .. you design later when the wizard leaves you in the Form Designer When an ActiveForm is deployed on the Web, Delphi creates an HTML page to contain the reference to the ActiveForm and specify its location on the page The ActiveForm can then displayed and run from a Web browser Inside the browser, the form behaves just like a stand-alone Delphi form The form can contain any VCL components or ActiveX controls,... an ActiveX wrapper object for the VCL control For Active forms, this class is always TActiveFormControl For other ActiveX controls, it has a name of the form TVCLClassX, where TVCLClass is the name of the VCL control class Thus, for example, the ActiveX wrapper for TButton would be named TButtonX The wrapper class is a descendant of TActiveXControl, which provides support for the ActiveX interfaces... control without using a wizard For that information, refer to your Microsoft Developer’s Network (MSDN) documentation or search the Microsoft Web site for ActiveX information Creating an ActiveX control 45-1 Overview of ActiveX control creation Overview of ActiveX control creation Creating ActiveX controls using Delphi is very similar to creating ordinary controls or forms This differs markedly from... control, the interface it exposes to clients, and any type definitions that these require For more information about the type library, refer to Chapter 41, “Working with type libraries.” • A form that descends from TActiveForm This form appears in the form designer, where you can use it to visually design the Active Form that appears to clients Its implementation appears in the generated implementation... setting up TActiveFormControl as the ActiveX wrapper for this form • An About box form and unit if you requested them • A LIC file if you enabled licensing At this point, you can add controls and design the form as you like After you have designed and compiled the ActiveForm project into an ActiveX library (which has the OCX extension), you can deploy the project to your Web server and Delphi creates... path on the Web server This can be a local path name or a UNC path, for example, C:\INETPUB\wwwroot 3 Set the Target URL to the location as a Uniform Resource Locators (URL) of the ActiveX control DLL (without the file name) on your Web Server, for example, http://mymachine .borland. com/ See the documentation for your Web Server for more information on how to do this Creating an ActiveX control 45-15 Deploying... a dialog-like interface for a property For information on how to create property pages, see “Creating a property page for an ActiveX control” on page 45-12 Creating an ActiveX control 45-3 Designing an ActiveX control Designing an ActiveX control When designing an ActiveX control, you start by creating a custom VCL control This forms the basis of your ActiveX control For information on creating custom... forms Active forms let you use the form designer to create a more elaborate control that acts like a dialog or like a complete application You develop the Active form in much the same way that you develop a typical Delphi application Active Forms are typically intended for deployment on the Web This chapter provides an overview of how to create an ActiveX control in the Delphi environment It is not intended . new Active Form, perform the following steps: 1 Use the ActiveForm wizard to create an Active Form, which appears as a blank form in the IDE, and an associated ActiveX wrapper for that form. 2 Use. using a wizard. For that information, refer to your Microsoft Developer’s Network (MSDN) documentation or search the Microsoft Web site for ActiveX information. 45-2 Developer’ s Guide Overview. object is an ActiveX wrapper object for the VCL control. For Active forms, this class is always TActiveFormControl. For other ActiveX controls, it has a name of the form TVCLClassX, where TVCLClass