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 that follow, see About Object Property Descriptions.

Objects of this class have the following properties:

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.

Property 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.

Property 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 a null string

Property 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.

Property 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.

Property 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.

Property 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 there are two connections — a control channel and a data channel — established with the remote FTP server.

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)

Property 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.

Warning
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: '' 



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 the null 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: */*

Property 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.

Property 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.

Property 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.

Property 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).

Property 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.

Property 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 a null string. This property will also contain a null 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.

Property 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.

Property 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).

Property 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.

Property 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).

Property 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.

Property 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.

Property Type

Int

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

The default is 1800 seconds.

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.

Property 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.

Property 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 a null 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.

Property 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.

Property 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 a null 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.

Property 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.

Property 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.

Property 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).

Property Type

Boolean

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No