>  Docs Center  >  IDL Reference  >  I/O - Network  >  IDLnetURL Properties

IDLnetURL Properties

IDLnetURL Properties

IDLnetURL objects have the following properties. Properties with the word “Yes” in the “Init” column of the property table can be set with IDLnetURL::Init.

Note: For a discussion of the property description tables shown below, see Modifying Object Property Descriptions.

Objects of this class have the following properties:

AUTHENTICATION

CALLBACK_DATA

CALLBACK_FUNCTION

CONNECT_TIMEOUT

CONTENT_TYPE

ENCODE

FTP_CONNECTION_MODE

HEADERS

PROXY_AUTHENTICATION

PROXY_HOSTNAME

PROXY_PASSWORD

PROXY_PORT

PROXY_USERNAME

RESPONSE_CODE

RESPONSE_FILENAME

RESPONSE_HEADER

SSL_CERTIFICATE_FILE

SSL_VERIFY_HOST

SSL_VERIFY_PEER

SSL_VERSION

TIMEOUT

URL_HOSTNAME

URL_PASSWORD

URL_PATH

URL_PORT

URL_QUERY

URL_SCHEME

URL_USERNAME

VERBOSE

 

AUTHENTICATION

This property determines the type of authentication used when connecting to a remote server. If AUTHENTICATION is enabled, the server expects to receive both a username and password, either specified through the URL_USERNAME and URL_PASSWORD properties, or in a URL specified explicitly in the Get or Put method. IDL does not check to make sure the username and password are provided, but the remote server may generate an error if they are not.

Supported authentication modes are:

0

Disabled

Authentication is disabled. This is the default.

1

Basic Only

Username and password are sent as plain text.

2

Digest Only

Username and password are encrypted before being sent.

3

Basic and Digest

Either basic or digest is used depending on the mode preferred by the remote server.

Type

Integer

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

CALLBACK_DATA

This property contains data that is passed to the caller when a callback is made. The data contained in this variable is defined and set by the caller. The variable is passed, unmodified, directly to the caller as a parameter in the callback function. If this property is not set, the Get, Put, GetFtpDirList, and FtpCommand methods pass an undefined variable.

Type

Any IDL variable

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

CALLBACK_FUNCTION

This property is the name of the IDL function to be called when the Get, Put, GetFtpDirList, and FtpCommand methods are retrieving information from the remote server. The callbacks provide feedback to the user about the ongoing operation, as well as provide a method to cancel an ongoing operation. If this property is not set, the Get, Put, GetFtpDirList, and FtpCommand methods will not make a callback to the IDL caller.

For information on creating a callback function, see Using Callbacks with the IDLnetURL Object.

The default value is an empty string

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

CONNECT_TIMEOUT

This property controls how long, in seconds, the object will wait for a successful connection to a remote HTTP or FTP server. The default is 180 seconds.

Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

CONTENT_TYPE

This property contains the type of the last document received when an HTTP Get request was issued. This property only applies to an HTTP Get call, and is set from the partial contents of the Content-Type field found in an HTTP response header.

Type

String

Name String

not displayed

Get: Yes

Set: No

Init:No

Registered: No

ENCODE

This property determines if a compressed/encoded response is requested from a remote HTTP server. By default, the IDLnetURL object requests that the server respond with compressed/encoded data to reduce the number of bytes sent over the network. The server does not have to respond with compressed/encoded data even if this object requests such a response. If the server does respond with compressed/encoded data, the server also sets the Content-Encoding header in the response to the type of compression/encoding used.

The valid property values are:

0

Do not request an encoded response.

“Accept-Encoding:” is not sent in the request.

If the server still sends a compressed/encoded response (even though not requested), the response is not decompressed/decoded and the output file is written with the compressed/encoded data.

1

Request and accept a deflate response.

“Accept-Encoding: deflate” is added to the request header.

If the server replies with a compressed/encoded response, the response is decompressed/decoded before being written to the output file.

2

Request and accept a GZIP response.

“Accept-Encoding: gzip” is added to the request header.

If the server replies with a compressed/encoded response, the response is decompressed/decoded before being written to the output file.

3

Request and accept deflate or gzip responses.

“Accept-Encoding: deflate, gzip” is added to the request header.

If the server replies with a compressed/encoded response, the response is decompressed/decoded before being written to the output file.

This is the default value.

Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

FTP_CONNECTION_MODE

This property determines whether FTP uses an active or passive connection mode. During an FTP transaction two connections are established with the remote FTP server:a control channel and a data channel.

In passive mode, the IDL client creates both the control and data connections to the remote FTP server. In active mode, the IDL client only creates the control channel to the remote FTP server, and the remote FTP server creates the data channel connection to the IDL client. The security settings on your network may prevent active mode, passive mode, or both from working. If active mode fails, try passive mode. If passive mode fails, enable FTP transactions on your network.

The valid property values are:

0

Passive

1

Active (this is the default)

Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

HEADERS

Note: This property is set automatically and need not be modified unless you have specific HTTP header information that you want included in a request sent to an HTTP server. This property is ignored if the URL scheme is not HTTP or HTTPS.

Note: This property is automatically set to the default value (clearing any custom header information) after a call to either the IDLnetURL::Get or the IDLnetURL::Put method. Clearing the HEADERS property prevents the inadvertent use of custom header values in future calls to these methods.

Set this property to a string or array of strings containing one or more valid header fields and content values separated by a colon. Each string in the string array should contain a single header field. Set this property to an empty string (‘’) to clear any existing custom headers.

If you add a custom header with no contents (‘Accept:’, for example, has no data on the right side of the colon), the internally-used header is disabled. This property allows you to add new headers, and replace and remove internal headers.

To add a header with no contents, set the contents to two single quotes: (‘’). For example:

MyHeader: ''

If your url host requires a 'User-Agent:' field it can be set in the header property. For example:

Obj->SetProperty, HEADERS = 'User-Agent: <user agent value>'

 

Note: The first line in an HTTP request usually looks something like:

GET / HTTP/1.1

This line is not a header, and should not be included in any specification of the HEADERS property. Including lines that are not of the form

Header : value

will result in an invalid HTTP request.

Retrieving the value of the HEADERS property using the GetProperty method only returns the headers that have been explicitly set by the user. GetProperty calls do not return the headers that are automatically set when this property is not set or is explicitly set to an empty string. To see the headers that are sent in the request, along with the request itself, set the VERBOSE property.

The following are examples of some HTTP headers that are automatically set for the user:

Host: motherlode.rsi.edu
Accept: */*

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

PROXY_AUTHENTICATION

This property determines the type of authentication used when connecting to a proxy server. When authentication is enabled, the PROXY_USERNAME and PROXY_PASSWORD properties must be set. If these properties are not set, the PROXY_AUTHENTICATION property is ignored.

The following authentication modes are supported:

0

Disabled

Proxy authentication is disabled. This is the default.

1

Basic Only

The PROXY_USERNAME and PROXY_PASSWORD properties are sent as plain text.

2

Digest Only

The PROXY_USERNAME and PROXY_PASSWORD properties are encrypted before being sent.

3

Basic and Digest

Either the basic or digest mode can be used, depending upon the remote server’s preference.

Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

PROXY_HOSTNAME

This property holds a proxy server name, which can be a host name or a numeric IP address. PROXY_HOSTNAME is used when connecting to an intranet or the Internet through a proxy.

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

PROXY_PASSWORD

This property is used when authenticating with a proxy server.

Type

String

Name String

not displayed

Get: No

Set: Yes

Init:Yes

Registered: No

PROXY_PORT

This property value is the TCP/IP port that the proxy server monitors for incoming requests. The default value is 80 (the standard HTTP port).

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

PROXY_USERNAME

This property is used when authenticating with a proxy server.

Property Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

RESPONSE_CODE

This property contains the HTTP/FTP response code for the last HTTP or FTP request sent to the remote server. It can be useful to examine the value of this property when an error has occurred.

See HTTP and FTP Response Codes for a listing of common response codes.

Type

Int

Name String

not displayed

Get: Yes

Set: No

Init:No

Registered: No

RESPONSE_FILENAME

This property contains the name of an error response file sent when a transmission error occurs. If no error has occurred, this property will contain an empty string. This property will also contain an empty string if a transmission error occurs, but no error file is received from the remote server.

Note: This property should only be used after catching an error.

Type

String

Name String

not displayed

Get: Yes

Set: No

Init:No

Registered: No

RESPONSE_HEADER

This property contains the HTTP or FTP response header for the last request sent to the remote HTTP or FTP server. It can be useful to examine the value of this property when an error has occurred.

Type

String

Name String

not displayed

Get: Yes

Set: No

Init:No

Registered: No

SSL_CERTIFICATE_FILE

This property is a string containing the fully-qualified path to a file containing one or more SSL certificates that verify the peer. IDL automatically installs a default bundle of CA certificates. The default value is the location of the certificates installed along with IDL (<IDL_DIR>/bin/bin.<platform>/ca-bundle.crt).

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

SSL_VERIFY_HOST

This property specifies whether the IDLnetURL object should verify the authenticity of the server certificate. When negotiating an SSL connection, the server sends a certificate indicating its identity. When SSL_VERIFY_HOST is 0, the connection succeeds regardless of what the certificate contains. When this property is non-zero (the default), the certificate must indicate that the server is your intended destination, or the connection fails.

The IDLnetURL object decides the server is the intended destination when the Common Name field or a Subject Alternate Name field in the certificate matches the host name in the destination URL.

Note: The server could be lying about its identity. To spot a dishonest server, refer to SSL_VERIFY_PEER.

Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

SSL_VERIFY_PEER

This property specifies whether the IDLnetURL object should verify the authenticity of the peer’s SSL certificate. When negotiating an SSL connection, the server sends a certificate proving its identity. The object verifies whether the certificate is authentic (that is, that you can trust that the server is who the certificate says it is). This trust is based on a chain of digital signatures, rooted in certification authority (CA) certificates you supply. IDL installs a default bundle of CA certificates, and you can specify alternate certificates with the SSL_CERTIFICATE_FILE property.

When this property is nonzero (the default) and the verification fails to prove that the certificate is authentic, the connection fails. When this property is zero, the connection always succeeds. Authenticating the certificate is not (by itself) very useful. You typically want to ensure that the server, as authenticated by its certificate, is the server you want to communicate with (use the SSL_VERIFY_HOST property to do that).

Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

SSL_VERSION

This property determines what version of the SSL/TLS protocol to use. The valid values for this property are:

0

Automatic

Automatically determines the correct protocol version of SSL to use. The default value works with most remote HTTP or FTP servers. If the remote HTTP or FTP server does not support automatic determination of the protocol version, set this property to a specific version that is supported by the remote HTTP or FTP server. This is the default.

1

TLS Version 1

Use Transport Layer Security (TLS) version 1. TLS supersedes SSL.

2

SSL Version 2

Use Secure Socket Layer (SSL) version 2.

3

SSL Version 3

Use Secure Socket Layer (SSL) version 3.

Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

TIMEOUT

This property controls how long, in seconds, the object waits for the entire transfer from a remote HTTP or FTP server to complete. The default is 1800 seconds.

Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

URL_HOSTNAME

This property contains the name of the remote HTTP or FTP server, and can be a host name or IP address.

Refer to Mapping URL Components to IDLnetURL Properties for details on how to pull a host name from a URL.

Note: This and all other URL_* properties are ignored if the URL keyword is specified explicitly in calls to the Get, Put, GetFtpDirList, and FtpCommand methods.

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

URL_PASSWORD

This property is used when authenticating with a remote HTTP or FTP server. The value can be any string. The character “@” is appended. Refer to Mapping URL Components to IDLnetURL Properties for details on how to pull a path from a URL.

Note: This and all other URL_* properties are ignored if the URL keyword is specified explicitly in calls to the Get, Put, GetFtpDirList, and FtpCommand methods.

Type

String

Name String

not displayed

Get: No

Set: Yes

Init:Yes

Registered: No

URL_PATH

This value is the full path to the network resource to be retrieved by the Get method, the full path to the directory where an uploaded file is to be placed by the Put method, the path to the directory for which the directory listing is to be retrieved by the GetFtpDirList method, or the path to the directory in which the specified command is to be executed by the FtpCommand method.

If the value is not an empty string, IDL prepends the “/” character.

Refer to Mapping URL Components to IDLnetURL Properties for details on how to extract the path from a URL.

Note: This and all other “URL_” properties are ignored if the URL keyword is specified explicitly in calls to the Get, Put, GetFtpDirList, and FtpCommand methods.

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

URL_PORT

This value is the TCP/IP port that the remote HTTP or FTP server monitors for incoming requests. Refer to Mapping URL Components to IDLnetURL Properties for details on how to pull a path from a URL. The default is port 80 (the standard port for HTTP connections).

Note: This and all other URL_* properties are ignored if the URL keyword is specified explicitly in calls to the Get, Put, GetFtpDirList, and FtpCommand methods.

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

URL_QUERY

This value represents the portion of a URL that follows the “?” character when constructing the URL. If this value is not an empty string, IDL prepends the “?” character.

Refer to Mapping URL Components to IDLnetURL Properties for details on how to pull a path from a URL.

Note: This and all other URL_* properties are ignored if the URL keyword is specified explicitly in calls to the Get, Put, GetFtpDirList, and FtpCommand methods.

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

URL_SCHEME

This property contains the name of the protocol used to communicate with the remote server. The values are “http” (the default), “https”, “ftp”, and “ftps”. IDL automatically appends the string “://” to the end of this property. Refer to Mapping URL Components to IDLnetURL Properties for details on how to pull a path from a URL.

Note: This and all other URL_* properties are ignored if the URL keyword is specified explicitly in calls to the Get, Put, GetFtpDirList, and FtpCommand methods.

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

URL_USERNAME

This property is used when authenticating with a remote HTTP or FTP server. The value can be any string. The string “:” is appended if URL_PASSWORD is supplied; otherwise, the string “@” is appended.

Refer to Mapping URL Components to IDLnetURL Properties for details on how to pull a path from a URL.

Note: This and all other URL_* properties are ignored if the URL keyword is specified explicitly in calls to the Get, Put, GetFtpDirList, and FtpCommand methods.

Type

String

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No

VERBOSE

When this property is set in conjunction with the CALLBACK_FUNCTION property, the information contained in the statusInfo parameter of the callback function includes the following messages:

Message Type

Description

Info

Messages concerning the TCP/IP connection to the remote server

Header Out

Messages concerning the HTTP header fields or FTP commands being sent to the remote server

Header In

Messages concerning the HTTP header fields or FTP command responses received from the remote server

Each message is limited to 512 bytes of text.

The VERBOSE property is useful for looking at the contents of the HTTP or FTP messages being sent to and from the remote HTTP or FTP server. See Using Callbacks with the IDLnetURL Object for additional details.

By default, the VERBOSE property is set to 0 (false).

Type

Boolean

Name String

not displayed

Get: Yes

Set: Yes

Init:Yes

Registered: No



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us