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