Project

General

Profile

Up

_networkSetOption

Define an option; usually this definition is before a perform.
For that, there is one option (I) and one value (u0). If you need to add N options, call N times this function.

Prototype :

fun [ObjNetwork I u0] ObjNetwork

  • ObjNetwork : a network object created with _networkCreate.

  • I : an option :
    • NETWORK_OPTION_PROTOCOLS : limit what protocols libcurl may use in the transfer. By default, all knowns protocols (NETWORK_PROTOCOL_ALL) are used. See availables values below.

    • NETWORK_OPTION_FOLLOW_LOCATION : tells the library to follow any Location: header that the server sends as part of a HTTP header. If yes, set the value to 1.

    • NETWORK_OPTION_MAX_REDIRS : set number will be the redirection limit. nil or any negative number to define an infinite number. You must set to 1 NETWORK_OPTION_FOLLOW_LOCATION to use this option.

    • NETWORK_OPTION_REDIR_PROTOCOLS : limit what protocols libcurl may use in a transfer that it follows to in a redirect when NETWORK_OPTION_FOLLOW_LOCATION (above) is set to 1. The value is one of flags below. By default, all protocols except for FILE and SCP are allowed.

    • NETWORK_OPTION_LOCALPORT : set the local port number of the socket used for connection. The value must be a tuple of two items : the port to try and the range to retry (add one to the number for each retry).

    • NETWORK_OPTION_REMOTEPORT : force to remote port number to connect to, instead of the one specified in the URL or the default port for the used protocol.

    • NETWORK_OPTION_BUFFERSIZE : set the size (in bytes) for the receive buffer. If nil, set to the default libcurl value (16 ko).

    • NETWORK_OPTION_HTTP_AUTH : set which authentication method you want to use (see below).

    • NETWORK_OPTION_USERNAME : set the user name to use for the transfer.

    • NETWORK_OPTION_PASSWORD : set the password associated to an user name.

    • NETWORK_OPTION_AUTH_UNRESTRICTED : set (value = 1) the library it can continue to send authentication (user+password) when following locations, even when hostname changed. You must set NETWORK_OPTION_FOLLOW_LOCATION to 1 to use this option.

    • NETWORK_OPTION_COOKIE : set a cookie in the http request. The format of the string should be name=content, where name is the cookie name and content is what the cookie should contain. If you need to set multiple cookies, you need to set them all using a single option and thus you need to concatenate them all in one single string. Set multiple cookies in one string like this: "name1=content1; name2=content2; etc...".

    • NETWORK_OPTION_USERAGENT : customize the user-agent. By defaut, this is Scol_libcurl-agent/1.0. A string is expected.

    • NETWORK_OPTION_REFERRER : specify the referrer field, by example in an embedded link.

    • NETWORK_OPTION_HEADERS : set a list of HTTP headers to send into your request. Each header must be a string.

    • NETWORK_OPTION_FTP_PORT : set the IP address to use for the FTP PORT instruction (active connection, not passive). The string may be a plain IP address, a host name, a network interface name (under GNU/linux Scol version) or just a '-' symbol to let the library use your system's default IP address. Default FTP operations are passive, and thus won't use PORT.
      The address can be followed by a ':' to specify a port, optionally followed by a '-' to specify a port range. If the port specified is 0, the operating system will pick a free port. If a range is provided and all ports in the range are not available, libcurl will report CURLE_FTP_PORT_FAILED (30).

    • NETWORK_OPTION_S_FTP_DIRONLY : set a return with the name of the files and subdirectory in a folder. For FTP and SFTP protocol only.
      You must extract datas yourself from a callback (like _networkCBdownload).

    • NETWORK_OPTION_SSL_AUTH : set the desired level of SSL (for enabling SSL/TLS when FTP, SMTP, POP3, IMAP etc are used). Four level (I) are available (see below)

    • NETWORK_OPTION_FTP_AUTH : set the authentification mode for a FTP transfer. For the most cases, NETWORK_OPTION_SSL_AUTH (above) option must be enabled. Differents values are availables, see below.

    • NETWORK_OPTION_FTP_ACCT : set the account info, if required by the server (ACCT command). Typically sent after a PASS command.

    • NETWORK_OPTION_S_FTP_QUOTE : pass a list of commands. The associated value must be a tuple : [I [S r1]]. See below.

    • NETWORK_OPTION_FTP_APPEND : set to 1 to append to the remote file instead of overwrite it.

    • NETWORK_OPTION_URL : set the url (must be URL-encoded in the following format: scheme://host:port/path). Examples : "http://www.domain.tld", "http://login:password@www.domain.tld/folder/", "ftp://123.123.123.123/folder/file.ext", "smtp://mail.domain.tld:5151", ...

    • NETWORK_OPTION_HTTPGET : forces (1) the HTTP request to get back to GET. This can be useful after a POST, PUT, ... request with the same object.


  • u0 : a value depending on the choosen option above (see option abovve too) :

    • For NETWORK_OPTION_PROTOCOLS and NETWORK_OPTION_REDIR_PROTOCOLS options :

      I :
      NETWORK_PROTOCOL_HTTP, NETWORK_PROTOCOL_HTTPS, NETWORK_PROTOCOL_FTP, NETWORK_PROTOCOL_FTPS, NETWORK_PROTOCOL_SCP, NETWORK_PROTOCOL_SFTP, NETWORK_PROTOCOL_TELNET, NETWORK_PROTOCOL_LDAP, NETWORK_PROTOCOL_LDAPS, NETWORK_PROTOCOL_DICT, NETWORK_PROTOCOL_FILE, NETWORK_PROTOCOL_TFTP, NETWORK_PROTOCOL_IMAP, NETWORK_PROTOCOL_IMAPS, NETWORK_PROTOCOL_POP3, NETWORK_PROTOCOL_POP3S, NETWORK_PROTOCOL_SMTP, NETWORK_PROTOCOL_SMTPS, NETWORK_PROTOCOL_RTSP, NETWORK_PROTOCOL_RTMP, NETWORK_PROTOCOL_RTMPT, NETWORK_PROTOCOL_RTMPE, NETWORK_PROTOCOL_RTMPTE, NETWORK_PROTOCOL_RTMPS, NETWORK_PROTOCOL_RTMPTS, NETWORK_PROTOCOL_GOPHER, NETWORK_PROTOCOL_ALL

    • For NETWORK_OPTION_S_FTP_DIRONLY, NETWORK_OPTION_FOLLOW_LOCATION, NETWORK_OPTION_FTP_APPEND, NETWORK_OPTION_HTTPGET and NETWORK_OPTION_AUTH_UNRESTRICTED options :

      I :
      1 to enable

    • For NETWORK_OPTION_MAX_REDIRS, NETWORK_OPTION_BUFFERSIZE and NETWORK_OPTION_REMOTEPORT options :

      I :
      the number

    • For NETWORK_OPTION_LOCALPORT option :

      [I I] :
      a port between 1 and 65535 and the number of attempts should make to find a working local port number

    • For NETWORK_OPTION_S_FTP_QUOTE option :

      [I [S r1]] :

      1. Flag (I) :
        • NETWORK_S_FTP_QUOTE_PRIOR : the list of commands will be passed prior the request and before any other commands are issued (default flag).
        • NETWORK_S_FTP_QUOTE_PRE : the list of commands will be passed to the server after the transfer type is set
        • NETWORK_S_FTP_QUOTE_AFTER : the list of commands will be passed to the server after your FTP transfer request.
      2. A list of FTP commands ([S r1])

    • For NETWORK_OPTION_HTTP_AUTH option :

      I :

      • NETWORK_AUTH_NONE
      • NETWORK_AUTH_BASIC : HTTP Basic authentication. This sends the user name and password over the network in plain text. Mode by default.
      • NETWORK_AUTH_DIGEST : HTTP Digest authentication.
      • NETWORK_AUTH_NTLM : HTTP NTLM authentication (proprietary protocol made by Microsoft).
      • NETWORK_AUTH_GSSNEGOTIATE : HTTP GSS-Negotiate authentication.
      • NETWORK_AUTH_DIGEST_IE : HTTP Digest authentication with an IE flavor.
      • NETWORK_AUTH_ANY : sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure.
      • NETWORK_AUTH_ONLY : this value together with a single specific authentification value to force libcurl to probe for un-restricted authentification and if not, only that single auth algorithm is acceptable.
      • NETWORK_AUTH_ANYSAFE : sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure.

    • For NETWORK_OPTION_SSL_AUTH :

      I :

      • NETWORK_AUTH_NONE : no use SSL.
      • NETWORK_AUTH_SSL_TRY : try using SSL, proceed as normal otherwise.
      • NETWORK_AUTH_SSL_CONTROL : require SSL for the control connection (otherwise, fail).
      • NETWORK_AUTH_SSL_ALL : Require SSL for all communication (otherwise fail).

    • For NETWORK_OPTION_FTP_AUTH :

      I :

      • NETWORK_AUTH_FTP_DEFAULT : let libcurl decide (by default).
      • NETWORK_AUTH_FTP_SSL : try SSL and if fails then try TLS.
      • NETWORK_AUTH_FTP_TLS : try TLS and if fails then try SSL.

        • These 3 values below makes libcurl use CCC (Clear Command Channel). It shuts down the SSL/TLS layer after authenticating. The rest of the control channel communication will be unencrypted. This allows NAT routers to follow the FTP transaction.

      • NETWORK_AUTH_FTP_SSL_CCC_NONE : no use CCC.
      • NETWORK_AUTH_FTP_SSL_CCC_PASSIVE : do not initiate the shutdown, but wait for the server to do it. Do not send a reply.
      • NETWORK_AUTH_FTP_SSL_CCC_ACTIVE : initiate the shutdown and wait 3 for a reply.

    • For NETWORK_OPTION_USERNAME, NETWORK_OPTION_PASSWORD, NETWORK_OPTION_COOKIE, NETWORK_OPTION_USERAGENT, NETWORK_OPTION_REFERRER, NETWORK_OPTION_FTP_PORT, NETWORK_OPTION_FTP_ACCT, NETWORK_OPTION_URL options :

      S :
      a string

    • For NETWORK_OPTION_HEADERS :

      [S r1] :
      a list of strings

Return : ObjNetwork the same object.

See also :

Example :




Note :