Calling Server Interfaces
Go Up to Creating the Client Application
Contents
Applications do not need to call the IAppServer or IAppServerSOAP interface directly because the appropriate calls are made automatically when you use the properties and methods of the client dataset. However, while it is not necessary to work directly with the IAppServer or IAppServerSOAP interface, you may have added your own extensions to the remote data module's interface. When you extend the application server's interface, you need a way to call those extensions using the connection created by your connection component. Unless you are using SOAP, you can do this using the AppServer property of the connection component. AppServer is a Variant that represents the application server's interface.
To call this interface, you must obtain a dispatch interface from this Variant. The dispatch interface has the same name as the interface that was created when you created the remote data module, but with the string "Disp" appended.
Thus, if your remote data module is called MyAppServer, you can use AppServer to call its interface in C++, as follows:
IDispatch* disp = (IDispatch*)(MyConnection->AppServer)
IMyAppServerDisp tempInterface( (IMyAppServer*)disp);
TempInterface.SpecialMethod(x,y);
Note: The dispatch interface is declared in the _TLB.h file generated by the Type Library Editor.
If you are not using SOAP, you can call an interface method using AppServer by writing a statement in Delphi such as:
MyConnection.AppServer.SpecialMethod(x,y);
However, this technique provides late (dynamic) binding of the interface call. That is, the SpecialMethod procedure call is not bound until runtime when the call is executed. Late binding is very flexible, but by using it you lose many benefits such as Code Insight and type checking. In addition, late binding is slower than early binding, because the compiler generates additional calls to the server to set up interface calls before they are invoked.
Using early binding with DCOM
When you are using DCOM as a communications protocol with Delphi, you can use early binding of AppServer calls. Use the as operator to cast the AppServer variable to the IAppServer descendant you created when you created the data module. For example:
with MyConnection.AppServer as IMyAppServer do
SpecialMethod(x,y);
To use early binding under DCOM, the type library of the server must be registered on the client machine. You can use TRegSvr.exe, which ships with RAD Studio, to register the type library.
Note: The TRegSvr sample provides the source for TRegSvr.exe and shows how to register a type library programmatically. To find the TRegSvr sample, click Start | Programs | Embarcadero RAD Studio Alexandria | Samples and open the
Object Pascal\VCL\TRegSvrdirectory.
Using dispatch interfaces with TCP/IP or HTTP
When you are using TCP/IP or HTTP, you cannot use true early binding, but because the remote data module uses a dual interface, you can use the dispinterface of the application server to improve performance over simple late binding. The dispinterface has the same name as the remote data module's interface, with the string 'Disp' appended. You can assign the AppServer property to a variable of this type to obtain the dispinterface. Thus in Delphi:
var
TempInterface: IMyAppServerDisp;
begin
TempInterface :=IMyAppServerDisp(IDispatch(MyConnection.AppServer));
// …
TempInterface.SpecialMethod(x,y);
// …
end;
Note: To use the dispinterface, you must add the _TLB unit that is generated when you save the type library to the uses clause of your client module.
Calling the interface of a SOAP-based server
If you are using SOAP, you cannot use the AppServer property. Instead, you must use a remote interfaced object (THTTPRio) and make early-bound calls. As with all early-bound calls, the client application must know the application server’s interface declaration at compile time.
You can add this to your client application by referencing a WSDL document that describes the interface you want to call. Note that for SOAP servers, this interface is entirely separate from the interface of the SOAP data module. For information on importing a WSDL document that describes the interface, see Importing WSDL Documents.
The unit that declares the server interface must also register it with the invocation registry. For details on how to register invokable interfaces, see Understanding Invokable Interfaces. After you have imported a WSDL document in C++, to generate a unit declaring and registering the interface, create an instance of THTTPRio for the desired interface:
THTTPRio *X = new THTTPRio(NULL);
Next, assign the URL that your connection component uses to the remote interfaced object, appending the name of the interface you want to call:
X->URL = SoapConnection1.URL + "IMyInterface";
Now you can use the QueryInterface method to obtain an interface to call the server’s methods:
InterfaceVariable = X->QueryInterface(IMyInterfaceIntf);
if (InterfaceVariable)
{
InterfaceVariable->SpecialMethod(a,b);
}
Note that the call to QueryInterface takes as an argument the DelphiInterface wrapper for the invokable interface rather than the invokable interface itself.
If you are using SOAP, you cannot use the AppServer property. Instead, you must obtain the server's interface by calling the GetSOAPServer method. Before you call GetSOAPServer, however, you must take the following steps:
- Your client application must include the definition of the interface of the application server and register it with the invocation registry. You can add the definition of this interface to your client application by referencing a WSDL document that describes the interface you want to call. For information on importing a WSDL document that describes the server interface, see Understanding invokable interfaces.
- The TSOAPConnection component must have its Calling invokable interfaces.
- You must set the SOAPServerIID property of the SOAP connection component to the GUID of the server interface. You must set this property before your application connects to the server, because it tells the TSOAPConnection component what interface to fetch from the server.
Assuming the previous three conditions are met, you can fetch the server interface in Delphi as follows:
with MyConnection.GetSOAPServer as IMyAppServer do
SpecialMethod(x,y);