- AddToBypassList
- CreateInstance
- DynamicCast
- RemoveAuthentication
- RemoveBypassList
- SetBasicAuthentication
- SetBypassProxyOnLocal
- SetClientCertificateFile
- SetOptions
- SetProxyServer
- SetProxyServerOptions
- SetSoapLogFile
- SetTimeout
- SetUseDefaultProxySetting
- UseConnectionCache
- UseIntegratedWindowsAuthentication
Description
The SoapConnection class is used to create a proxy object for a specific Web service and set options for the connection.
Methods
SoapConnection has the following methods:
The GenerateProxy method is currently not implemented.
Description
Adds URIs to a list of locations that can be accessed without connecting to a proxy server. This method is available for .NET Web services only.
Syntax
conn.AddToBypassList (string value)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection |
|
value |
A regular expression that defines URIs that can be accessed without connecting to a proxy server. |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
You can use asterisks for wild cards in expressions for domain or host names and addresses. You can add multiple URIs to the bypass list in a single call by including semicolon separators to the value string expression.
See also
Description
Creates a proxy instance with a default URL for a SOAP server, which comes from a user-supplied WSDL file. The client application must create a proxy instance before it can access a Web service.
Syntax
conn.CreateInstance (ref powerobject proxy_obj, string proxy_name, {string portname}) throws SoapException
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection |
|
proxy_obj |
The referenced name of your proxy object |
|
proxy_name |
The name of the proxy, based on the port name from a URL in the WSDL file stored in the proxy |
|
portname |
(Optional) The port name from a URL not stored in the proxy |
Return value
Long.
Valid values are:
Examples
-
In this example, the client application creates a proxy instance to access the Web services at http://my.server/soap/myport. The proxy name "syb_myport" is generated by the Web Service Proxy wizard when you select "syb_" as a prefix for a service port (endpoint) called "myport".
syb_myport myproxy long ret ret = Conn.CreateInstance(myproxy, "syb_myport", "http://my.server/soap/myport")
-
The following script creates a connection to a Web service on a SOAP server. It sets the connection properties using an endpoint defined in the CreateInstance method. (If the endpoint is not defined in the CreateInstance method, a default URL stored in the proxy is used). The script uses the SetOptions method to specify a log file. It displays a return value in an application message box:
SoapConnection conn // Define SoapConnection syb_currencyexchangeport proxy_obj // Declare proxy long rVal, lLog real amount //Define endpoint. You can omit it, if you want to use //the default endpoint inside proxy string str_endpoint str_endpoint = "http://services.xmethods.net:80/soap" conn = create SoapConnection //Instantiated connection lLog = conn.SetOptions("SoapLog=~"C:\mySoapLog.log~"") // Set trace file to record soap interchange data, // if string is "", disables the feature rVal = Conn.CreateInstance(proxy_obj, & "syb_currencyexchangeport", str_endpoint) // Create proxy object try amount = proxy_obj.getrate("us","japan") // Invoke service messagebox("Current Exchange Rate", "One US Dollar"& + " is equal to " + string(amount) + " Japanese Yen") catch ( SoapException e ) messagebox ("Error", "Cannot invoke Web service") // error handling end try destroy conn
Usage
After you instantiate a proxy, you are ready to call the SOAP methods you want from the associated Web service port.
See also
Description
Dynamically casts a variable from one datatype (nonvisual object or structure) to another datatype, and copies runtime data form the source datatype to the target datatype. However, you must make sure the data in source datatype can be conveted to the target datatype before you call this method.
This method is available for .NET Web services only.
Syntax
conn.DynamicCast (powerobject src, string targettype)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection |
|
src |
The PowerScript datatype that you want to convert |
|
targettype |
A string specifying the datatype to which you want to convert the object |
Return value
Powerobject.
An object of the datatype specified by the targettype variable.
Examples
The following code converts a returned message from the msgA datatype to the msgB datatype.
Try msgA = myReport.GetMessage() MessageB msgB msgB = lsc_connection.dynamiccast(msgA, "MessageB") Catch (SoapException e) ... End Try
Usage
Some Web services return runtime data of a subclass even though the definition of the Web service method uses a base class. You can call the DynamicCast method to cast the proxy object for the subclass to the proxy object for the base class.
After you convert the object to the datatype you want, you can access every field in that object.
Description
Removes authentication for a Web service connection.
Syntax
conn.RemoveAuthentication ()
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
This method clears Basic, Digest, and Integrated Windows Authentication information. You can set authentication with the UseIntegratedWindowsAuthentication (.NET Web service clients only), SetBasicAuthentication, or SetOptions methods.
See also
Description
Removes the list of URIs to access without connecting to a proxy server. This method is available for .NET Web services only.
Syntax
conn.RemoveBypassList ()
Return value
Long.
Valid values are 0 for success, and 50 for failure.
See also
Description
Determines whether the SoapConnection object uses basic authentication for a Web service connection.
Syntax
conn.SetBasicAuthentication (string domain, string userID, string password)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
domain |
A string for the Web domain to which the user belongs. This could be a domain name, such as "appeon.com", or a machine name. |
|
userID |
A string for an https connection. |
|
password |
A string for an https connection. |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
You can call the SetBasicAuthentication method instead of including client identification information in the options argument of the SetOptions method.
If you are using .NET Web services, you can call the UseIntegratedWindowsAuthentication method for Integrated Windows Authentication.
See also
Description
Indicates whether to bypass the proxy server when connecting to Web services running on local servers. This method is available for .NET Web services only.
Syntax
conn.SetBypassProxyOnLocal (boolean bypass)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
bypass |
A boolean value that, when true, allows a connection to a local resource without using a proxy server. All internet requests are made through the proxy server when this value is false. |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
Local requests use the localhost or loopback domains, or a local IP address. Addresses without a period in the URI are also identified as being local.
See also
Description
Sets the certificate file or files to use to connect to a Web service. This method is available for .NET Web services only.
Syntax
conn.SetClientCertificateFile (string filename)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
filename |
A string containing the name of the certificate file or files you want to use to connect to a Web service. You must use a semicolon as a separator for multiple files. The value can include local files with a full path and URLs to remote certificate files. To discontinue use of certificates, enter an empty string (""). |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
You can call the SetClientCertificateFile method instead of including certificate information in the options argument of the SetOptions method.
See also
Description
Sets connection options for SoapConnection class.
Syntax
conn.SetOptions (string options)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
options |
Options you want to set for your connection. The string values for the option names are not case sensitive. These can be: SoapLog (EasySoap Web service engine only) The file path for SoapLog. To disable the log, enter "". UserID A string value for an https connection. Password A string value for an https connection. Domain (.NET Web service engine only) A string value for the Web domain to which the user belongs. This could be a domain name, such as "appeon.com", or a machine name. UseWindowsAuthentication (.NET Web service engine only) A "yes" or "no" value to determine whether to use "Integrated Windows Authentication". The value you enter can be a boolean or a string. If this option is set to "yes", you do not need to set the UserID, Password, or Domain options. AuthenticationMode (.NET Web service engine only) A string value for the authentication mode to use. This can be "basic" or "digest". These AuthenticationMode values are described on the Microsoft MSDN Web site at http://msdn.microsoft.com/en-us/library/aa833874(VS.80).aspx. CertificateFile (.NET Web service engine only) A string value for the certificate file or files that you want to send from the Web service client to the server. The string value could include local files with a full path and URLs to remote certificate files. You must use a semicolon as a separator for multiple files. Timeout A number for the maximum wait time in seconds. The default timeout value is 0, meaning that no limit to the connection time is set. ConnectionCache (EasySoap Web service engine only) A boolean that determines whether the http connection of the proxy instance is kept alive after a call to the proxy. The default value is false. |
Return value
Long.
Valid values are 0 for success, and 50 for failure. If multiple options are specified and the return value is 50, options specified before the failure are still valid.
Examples
In this example, the application enables the logging function and attempts to connect to an endpoint for which no user ID, password, or timeout has been set.
lOpt=Conn.SetOptions("SoapLog=~"airportweather.log~"")To avoid using escape characters before a second pair of quotation marks, use single quotation marks instead, or you can start an exterior string with single quotation marks and use double quotation marks around an interior string:
lOpt=Conn.SetOptions('SoapLog="airportweather.log"')Usage
User ID and password values can be set in an endpoint used by the SoapConnection class or by including these values as arguments to the SetOptions method.
Priority is given to values set in an endpoint (port) that is passed as an argument to the CreateInstance method of the SoapConnection class. However, a default endpoint is used when an endpoint is not set in the CreateInstance method. In this case, priority is given to user ID and password values defined in the SetOptions method.
If the endpoint used by the SoapConnection class does not have user ID and password values, and you do not set a user ID or password with the SetOptions method, the SoapConnection class connects to a SOAP server without giving a user ID or password.
If a user ID is defined in either the endpoint or the SetOptions method but is not a password, the password value is taken to be an empty string.
When you set a timeout other than the default, an exception is thrown after the Web service connection times out. Even if you do not set a timeout value from the client, the Web server can cause the request to time out on the server side.
If you include ConnectionCache as an argument in a SetOptions call, you must not use quotation marks to enclose the value that you set for this option.
Although SetOptions takes a single string argument for all available options, you can set each of the options with more specific methods. You can use the following methods to replace SetOptions:
See also
Description
Sets the address, port, user name, and password for the proxy server. This method has two syntaxes.
Syntax
conn.SetProxyServer (string address, string userID, string password) conn.SetProxyServer (string hostname, long port, string userID, string password)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection |
|
address |
A string containing the host name address and port of the proxy server, and optionally, an endpoint, in the format: http://hostname:port/path |
|
hostname |
A string containing the host name |
|
port |
A long for the proxy server port |
|
userID |
A string containing the user ID for the proxy server |
|
password |
A string containing the proxy server password |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Examples
This example uses the four-argument syntax of SetProxyServer:
long ll_return
ll_return = Conn.SetProxyServer &
("http://myProxyServer",8080, "My Name", "My Pass")Usage
This method does the same thing as the SetProxyServerOptions method, but it has a different syntax.
Use this method or the SetProxyServerOptions method if the proxy server requires authentication. The user ID and password that you supply with the SetOptions or other authentication methods apply to the URL of the Web service, not the proxy server.
See also
Description
Sets the proxy address, user name, and password for the proxy server.
Syntax
conn.SetProxyServerOptions (string optionstring)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
optionstring |
A string containing comma-separated name/value pairs. The format is: "address='proxy_endpoint '{, userID='name ', password='password '} "The address is required and can have a format such as: http://hostname:port/path Specify values for userID and password if the proxy server requires them. |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Examples
This example specifies a user name and password, as well as the proxy endpoint:
long ll_return string ls_string ls_string = "address='http://Srvr:8080/endpnt'," ls_string += "userID='MyName', password='mypass'" ll_return = Conn.SetProxyServerOptions (ls_string)
Usage
Use this method or the SetProxyServer method if the proxy server requires authentication. The user ID and password that you supply with the SetOptions or other authentication methods apply to the URL of the Web service, not the proxy server.
See also
Description
Sets the name of a file for logging raw SOAP messages. This method is available for EasySoap Web services only.
Syntax
conn.SetSoapLogFile (string filename)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
filename |
A string containing the full file name for the SOAP log file. To disable logging, enter an empty string (""). |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
You can call the SetSOAPLogFile method instead of including a log file name in the options argument of the SetOptions method.
See also
Description
Sets the timeout value for a SOAP connection.
Syntax
conn.SetTimeout (long seconds)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
seconds |
The timeout value in seconds. If this option is set to 0, no timeout will be set on the client side. (The Web service might still have a timeout value on the server side.) |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
You can call the SetTimeout method instead of including a timeout value in the options argument of the SetOptions method.
See also
Description
Indicates whether to use Internet Explorer proxy settings for a SOAP connection. This method is available for .NET Web services only.
Syntax
conn.SetUseDefaultProxySetting (boolean useDefault)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
useDefault |
A boolean value that, when true, uses the Internet Explorer proxy settings to connect to a Web service. When this value is false (default), the proxy server settings can be assigned by the SetProxyOption, SetBypassOnLocal, AddToBypassList, and RemoveBypassList methods. |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
If you do not set a proxy server, PowerBuilder uses the Internet Explorer proxy settings.
See also
Description
Determines whether a connection cache is used for the Web service connection. This method is available for EasySoap Web services only.
Syntax
conn.UseConnectionCache (boolean cache)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
cache |
A boolean that determines whether the http connection of the proxy instance is kept alive after a call to the proxy. The default value is false. |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
You can call the UseConnectionCache method instead of setting a connection cache in the options argument of the SetOptions method.
See also
Description
Determines whether the SoapConnection object uses Integrated Windows Authentication to connect to a Web service. This method is available for .NET Web services only.
Syntax
conn.UseIntegratedWindowsAuthentication (boolean useIWA)
|
Argument |
Description |
|---|---|
|
conn |
The name of the SoapConnection object that establishes the connection. |
|
useIWA |
A boolean that determines whether to use Integrated Windows Authentication. If this option is set to "yes", you do not need to set the UserID, Password, or Domain options. |
Return value
Long.
Valid values are 0 for success, and 50 for failure.
Usage
You can call the UseIntegratedWindowsAuthentication method to set connection authentication instead of the options argument of the SetOptions method.
See also
