SetWSDL

(System Library)

Description:	Connects a Realm with a WSDL file and a set of VTScada modules to enable a web service interface.
Returns	Numeric (0 for success, 1 for failure)
Usage:	Script Only.
Function Groups:	XML
Related to:	RemWSDL \| XMLProcessor \| XMLAddSchema \| XMLParse \| XMLWrite
Format:	System.Webservice\SetWSDL(WSDLFilePath, Realm, CallScope, Service[, pResponse, XSDFileName, WSDrvrVarName, AdditionalSchemas, AuthenticationModule])
Parameters:

WSDL File Path

Required. This is a file path that indicates where the WSDL file to be used for this service is located. The file path must be encoded in URL format. Only one WSDL file can be declared and it must be passed in the first parameter.

Realm

Required. The name of the VTScada Realm which will be used to expose the web service. Only one Realm can be specified and it must be passed as the second parameter.

Call Scope

Required. An instance (object) of the module in which all of the modules to be called are nested. This provides the scope for the remote module calls by the WebService engine. Only one call scope object can be specified and it must be passed as the third parameter.

Service

Required. The name of the web service to be presented as portrayed in the WSDL's Service tag. This is a string that must match the "name" attribute of the representative Service tag and tells the SetWSDL function where to start searching for data.

pResponse

Optional. A pointer to a variable that will be loaded with the error description should SetWSDL fail. This description takes the form of a single human readable string. The variable will be set to invalid if no error occurs.

XSDFileName

Optional text. File name for the output XSD file. If not specified, a temporary file is used.

WSDrvrVarName

Optional text. Name of variable to be added into the call scope. Useful if setting multiple WSDL/Realms into same scope.

AdditionalSchemas

Optional dictionary. If used, contains a dictionary of additional schemas required by the WDSL document to allow correct validation of it. The keys of the dictionary are the namespaces and the values are the paths to the files containing each schema.

AuthenticationModule

Optional text. If supplied, this is the name of a module, to be found in CallScope, that will be called when a SOAP request for the SOAP service is made, in order to obtain authentication credentials from the SOAP payload. See discussion in the Comments section.

Comments:

Linkage is first applied between the WSDL file and the VTScada modules by generating an XML schema using the WSDL and the parameters provided to this function. The Realm's address is then registered with the VTScada HTTP server to connect the whole thing to the network.

Inclusion of the parameter, pResponse is recommended, for the sake of obtaining error messages when debugging.

AuthenticationModule, if supplied, must be a subroutine and have the following format:

AuthModule(SOAPPackage, pUsername, pPassword, pPrivilege);

where:

SOAPPackage

Is the SOAP payload as an XML node tree

pUsername

Is a pointer to a variable that the AuthModule should store the username extracted from the SOAP payload.

pPassword

Is a pointer to a variable that the AuthModule should store the password extracted from the SOAP payload

pPrivilege

Is a pointer to a variable holding the privilege that the user account must have in order to execute the methods contained in the SOAP payload.

The AuthModule must provide a privilege, otherwise the request will be rejected.

An example AuthModule might look like the following:

]

Authenticate
(
  SOAPPackage { The SOAP payload as an XML node tree };
  pUsername   { Where to store the username };
  pPassword   { Where to store the password };
  pPrivilege  { Where to store a privilege };
)

Authenticate [
If 1;
[
  *pUsername = SOAPPackage\Envelope\Header\TestHeader\#attribs["UserID"];
  *pPassword = SOAPPackage\Envelope\Header\TestHeader\#attribs["Password"];
  *pPrivilege = AppPrivSOAP;
  Return();
]

Example:

Init [
  If Watch(1);
  [
    ServiceActive = System.WebService\SetWSDL(
       "file://C:/vts/StationExample/TagQueryServices.wsdl",
       "QueryServicesRealm",
       Self,
       "TagQueryServices",
       &ErrMsg);
  ]
]