# 13. Protocols

  ## Module Protocols.HTTP

    Method delete_url

      ``.Query` delete_url(`string`|`Standards.URI` `url`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`)`

    Description

      Sends a HTTP DELETE request to the server in the URL and returns the created and initialized `Query` object. `0` is returned upon failure. If a query object having `request_headers->Connection=="Keep-Alive"` from a previous request is provided and the already established server connection can be used for the next request, you may gain some performance.

    Method do_async_method

      ``void` do_async_method(`string` `method`, `string`|`Standards.URI` `url`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `Protocols.HTTP.Query` `con`, `void`|`string` `data`)`

    Description

      Low level asynchronous HTTP call method.

    Parameter `method`

      The HTTP method to use, e.g. `"GET"`.

    Parameter `url`

      The URL to perform `method` on. Should be a complete URL, including protocol, e.g. `"https://pike.lysator.liu.se/"`.

    Parameter `query_variables`

      Calls `http_encode_query` and appends the result to the URL.

    Parameter `request_headers`

      The HTTP headers to be added to the request. By default the headers User-agent, Host and, if needed by the url, Authorization will be added, with generated contents. Providing these headers will override the default. Setting the value to 0 will remove that header from the request.

    Parameter `con`

      Previously initialized connection object. In particular the callbacks must have been set (`Query.set_callbacks()`).

    Parameter `data`

      Data payload to be transmitted in the request.

    See also

      `do_method()`, `Query.set_callbacks()`

    Method do_async_proxied_method

      ``void` do_async_proxied_method(`string`|`Standards.URI` `proxy`, `string` `user`, `string` `password`, `string` `method`, `string`|`Standards.URI` `url`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `Protocols.HTTP.Query` `con`, `void`|`string` `data`)`

    Description

      Low level asynchronous proxied HTTP call method.

      Makes an HTTP request through a proxy.

    Parameter `proxy`

      URL for the proxy.

    Parameter `user`
    Parameter `password`

      Proxy authentication credentials.

    Parameter `method`

      The HTTP method to use, e.g. `"GET"`.

    Parameter `url`

      The URL to perform `method` on. Should be a complete URL, including protocol, e.g. `"https://pike.lysator.liu.se/"`.

    Parameter `query_variables`

      Calls `http_encode_query` and appends the result to the URL.

    Parameter `request_headers`

      The HTTP headers to be added to the request. By default the headers User-agent, Host and, if needed by the url, Authorization will be added, with generated contents. Providing these headers will override the default. Setting the value to 0 will remove that header from the request.

    Parameter `con`

      Previously initialized connection object. In particular the callbacks must have been set (`Query.set_callbacks()`).

    Parameter `data`

      Data payload to be transmitted in the request.

    See also

      `do_async_method()`, `do_proxied_method()`, `Query.set_callbacks()`

    Method do_method

      ``.Query` do_method(`string` `method`, `string`|`Standards.URI` `url`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`, `void`|`string` `data`)`

    Description

      Low level HTTP call method.

    Parameter `method`

      The HTTP method to use, e.g. `"GET"`.

    Parameter `url`

      The URL to perform `method` on. Should be a complete URL, including protocol, e.g. `"https://pike.lysator.liu.se/"`.

    Parameter `query_variables`

      Calls `http_encode_query` and appends the result to the URL.

    Parameter `request_headers`

      The HTTP headers to be added to the request. By default the headers User-agent, Host and, if needed by the url, Authorization will be added, with generated contents. Providing these headers will override the default. Setting the value to 0 will remove that header from the request.

    Parameter `con`

      Old connection object.

    Parameter `data`

      Data payload to be transmitted in the request.

    See also

      `do_sync_method()`

    Method do_proxied_method

      ``.Query` do_proxied_method(`string`|`Standards.URI` `proxy`, `string` `user`, `string` `password`, `string` `method`, `string`|`Standards.URI` `url`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`, `void`|`string` `data`)`

    Description

      Makes an HTTP request through a proxy.

    Parameter `proxy`

      URL for the proxy.

    Parameter `user`
    Parameter `password`

      Proxy authentication credentials.

    Parameter `method`
    Parameter `url`
    Parameter `query_variables`
    Parameter `request_headers`
    Parameter `con`
    Parameter `data`

      The remaining arguments are identical to `do_method()`.

    See also

      `do_method()`, `do_async_proxied_method()`

    Method get_url

      ``.Query` get_url(`string`|`Standards.URI` `url`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`)`

    Description

      Sends a HTTP GET request to the server in the URL and returns the created and initialized `Query` object. `0` is returned upon failure. If a query object having `request_headers->Connection=="Keep-Alive"` from a previous request is provided and the already established server connection can be used for the next request, you may gain some performance.

    Method get_url_data

      ``string` get_url_data(`string`|`Standards.URI` `url`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`)`

    Description

      Returns the returned data after calling the requested server for information through HTTP GET. `0` is returned upon failure. Redirects (HTTP 302) are automatically followed.

    Method get_url_nice

      ``array`(`string`) get_url_nice(`string`|`Standards.URI` `url`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`)`

    Description

      Returns an array of `({content_type, data})` after calling the requested server for the information. `0` is returned upon failure. Redirects (HTTP 302) are automatically followed.

    Method http_encode_cookie

      ``__deprecated__` `string` http_encode_cookie(`string` `f`)`

    Description

      This function used to claim that it encodes the specified string according to the HTTP cookie standard. If fact it does not - it applies URI-style (i.e. `%XX`) encoding on some of the characters that cannot occur literally in cookie values. There exist some web servers (read Roxen and forks) that usually perform a corresponding nonstandard decoding of %-style escapes in cookie values in received requests.

      This function is deprecated. The function `quoted_string_encode` performs encoding according to the standard, but it is not safe to use with arbitrary chars. Thus URI-style encoding using `uri_encode` or `percent_encode` is normally a good choice, if you can use `uri_decode`/`percent_decode` at the decoding end.

    Deprecated

    Method http_encode_query

      ``string` http_encode_query(`mapping`(`string`:`int`|`string`|`array`(`string`)) `variables`)`

    Description

      Encodes a query mapping to a string; this protects odd - in http perspective - characters like '&' and '#' and control characters, and packs the result together in a HTTP query string.

      Example:

          	> Protocols.HTTP.http_encode_query( (["anna":"eva","lilith":"blue"]) );
               Result: "lilith=blue&anna=eva"
               > Protocols.HTTP.http_encode_query( (["&amp;":"&","'=\"":"\0\0\0"]) );
               Result: "%26amp%3b=%26&%27%3d%22=%00%00%00"

    Method http_encode_string

      ``__deprecated__` `string` http_encode_string(`string` `in`)`

    Description

      This is a deprecated alias for `uri_encode`, for compatibility with Pike 7.6 and earlier.

      In 7.6 this function didn't handle 8-bit and wider chars correctly. It encoded 8-bit chars directly to `%XX` escapes, and it used nonstandard `%uXXXX` escapes for 16-bit chars.

      That is considered a bug, and hence the function is changed. If you need the old buggy encoding then use the 7.6 compatibility version (`#pike 7.6`).

    Deprecated

      Replaced by `uri_encode`.

    Method iri_encode

      ``string` iri_encode(`string` `s`)`

    Description

      Encodes the given string using `%XX` encoding to be used as a component part in an IRI (Internationalized Resource Identifier, see RFC 3987). This means that all chars outside the IRI `iunreserved` set are encoded, i.e. this function encodes equivalently to `uri_encode` except that all 8-bit and wider characters are left as-is.

    Bugs

      This function currently does not encode chars in the Unicode private ranges, although that is strictly speaking required in some but not all IRI components. That could change if it turns out to be a problem.

    See also

      `percent_decode`, `uri_encode`

    Method iri_normalize

      ``string` iri_normalize(`string` `s`)`

    Description

      Normalizes the IRI-style UTF-8 and `%XX` encoded string `s` by decoding all IRI `unreserved` chars, i.e. everything except the URI `reserved` chars and control chars.

      Since only unreserved chars are decoded, the result is always semantically equivalent to the input. It's therefore safe to use this on a complete formatted IRI.

    See also

      `iri_decode`, `uri_normalize`

    Method percent_decode

      ``string` percent_decode(`string` `s`)`

    Description

      Decodes URI-style `%XX` encoded chars in the given string.

    See also

      `percent_encode`, `uri_decode`

    Bugs

      This function currently does not accept wide string input, which is necessary to work as the reverse of `iri_encode`.

    Method percent_encode

      ``string` percent_encode(`string` `s`)`

    Description

      Encodes the given string using `%XX` encoding, except that URI unreserved chars are not encoded. The unreserved chars are `A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, and `~` (see RFC 2396 section 2.3).

      8-bit chars are encoded straight, and wider chars are not allowed. That means this encoding is applicable if `s` is a binary octet string. If it is a character string then `uri_encode` should be used instead.

      It is also slightly faster than `uri_encode` if `s` is known to contain only US-ASCII.

    Method post_url

      ``.Query` post_url(`string`|`Standards.URI` `url`, `mapping`(`string`:`int`|`string`|`array`(`string`))|`string` `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`)`

    Description

      Similar to `get_url`, except that query variables is sent as a POST request instead of a GET request. If query_variables is a simple string, it is assumed to contain the verbatim body of the POST request; Content-Type must be properly specified manually, in this case.

    Method post_url_data

      ``string` post_url_data(`string`|`Standards.URI` `url`, `mapping`(`string`:`int`|`string`|`array`(`string`))|`string` `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`)`

    Description

      Similar to `get_url_data`, except that query variables is sent as a POST request instead of a GET request.

    Method post_url_nice

      ``array`(`string`) post_url_nice(`string`|`Standards.URI` `url`, `mapping`(`string`:`int`|`string`|`array`(`string`))|`string` `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`)`

    Description

      Similar to `get_url_nice`, except that query variables is sent as a POST request instead of a GET request.

    Method put_url

      ``.Query` put_url(`string`|`Standards.URI` `url`, `void`|`string` `file`, `void`|`mapping`(`string`:`int`|`string`|`array`(`string`)) `query_variables`, `void`|`mapping`(`string`:`string`|`array`(`string`)) `request_headers`, `void`|`Protocols.HTTP.Query` `con`)`

    Description

      Sends a HTTP PUT request to the server in the URL and returns the created and initialized `Query` object. `0` is returned upon failure. If a query object having `request_headers->Connection=="Keep-Alive"` from a previous request is provided and the already established server connection can be used for the next request, you may gain some performance.

    Method quoted_string_decode

      ``string` quoted_string_decode(`string` `s`)`

    Description

      Decodes the given string which has been encoded as a `quoted-string` according to RFC 2616 section 2.2. `s` is assumed to not include the surrounding `"` chars.

    See also

      `quoted_string_encode`

    Method quoted_string_encode

      ``string` quoted_string_encode(`string` `s`)`

    Description

      Encodes the given string quoted to be used as content inside a `quoted-string` according to RFC 2616 section 2.2. The returned string does not include the surrounding `"` chars.

    Note

      The `quoted-string` quoting rules in RFC 2616 have several problems:

      - Quoting is inconsistent since `"` is quoted as `\"`, but `\` does not need to be quoted. This is resolved in the HTTP bis update to mandate quoting of `\` too, which this function performs.

      - Many characters are not quoted sufficiently to make the result safe to use in an HTTP header, so this quoting is not enough if `s` contains NUL, CR, LF, or any 8-bit or wider character.

    See also

      `quoted_string_decode`

    Method unentity

      ``__deprecated__` `string` unentity(`string` `s`)`

    Description

      Helper function for replacing HTML entities with the corresponding unicode characters.

    Deprecated

      Replaced by `Parser.parse_html_entities`.

    Method uri_decode

      ``string` uri_decode(`string` `s`)`

    Description

      Decodes URI-style `%XX` encoded chars in the given string, and then UTF-8 decodes the result. This is the reverse of `uri_encode` and `uri_encode_invalids`.

    See also

      `uri_encode`, `uri_encode_invalids`

    Method uri_encode

      ``string` uri_encode(`string` `s`)`

    Description

      Encodes the given string using `%XX` encoding to be used as a component part in a URI. This means that all URI reserved and excluded characters are encoded, i.e. everything except `A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, and `~` (see RFC 2396 section 2.3).

      8-bit chars and wider are encoded using UTF-8 followed by percent-encoding. This follows RFC 3986 section 2.5, the IRI-to-URI conversion method in the IRI standard (RFC 3987) and appendix B.2 in the HTML 4.01 standard. It should work regardless of the charset used in the XML document the URI might be inserted into.

    See also

      `uri_decode`, `uri_encode_invalids`, `iri_encode`

    Method uri_encode_invalids

      ``string` uri_encode_invalids(`string` `s`)`

    Description

      Encodes all "dangerous" chars in the given string using `%XX` encoding, so that it can be included as a URI in an HTTP message or header field. This includes control chars, space and various delimiter chars except those in the URI `reserved` set (RFC 2396 section 2.2).

      Since this function doesn't touch the URI `reserved` chars nor the escape char `%`, it can be used on a complete formatted URI or IRI.

      8-bit chars and wider are encoded using UTF-8 followed by percent-encoding. This follows RFC 3986 section 2.5, the IRI standard (RFC 3987) and appendix B.2 in the HTML 4.01 standard.

    Note

      The characters in the URI `reserved` set are: `:`, `/`, `?`, `#`, `[`, `]`, `@`, `!`, `$`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `;`, `=`. In addition, this function doesn't touch the escape char `%`.

    See also

      `uri_decode`, `uri_encode`

    Method uri_normalize

      ``string` uri_normalize(`string` `s`)`

    Description

      Normalizes the URI-style `%XX` encoded string `s` by decoding all URI `unreserved` chars, i.e. US-ASCII digits, letters, `-`, `.`, `_`, and `~`.

      Since only unreserved chars are decoded, the result is always semantically equivalent to the input. It's therefore safe to use this on a complete formatted URI.

    See also

      `uri_decode`, `uri_encode`, `iri_normalize`

    ## Class Protocols.HTTP.Query

      Description

        Open and execute an HTTP query.

      Example

            HTTP.Query o=HTTP.Query();
             void ok()
             {
                write("ok...\n");
                write("%O\n", o->headers);
                exit(0);
             }
             void fail()
             {
                write("fail\n");
                exit(0);
             }
             int main()
             {
                o->set_callbacks(ok, fail);
                o->async_request("pike.lysator.liu.se", 80, "HEAD / HTTP/1.0");
                return -1;
             }

      Method `()

        ``int` res = `Protocols.HTTP.Query()`()`

      Description

        Wait for connection to complete.

      Returns

        Returns `1` on successfull connection, `0` on failure.

      Method async_fetch

        ``void` async_fetch(`function`(:`void`) `callback`, `mixed` ... `extra`)`

      Description

        Fetch all data in background.

      See also

        `timed_async_fetch()`, `async_request()`, `set_callbacks()`

      Method set_callbacks
      Method async_request

        ``Protocols.HTTP.Query` set_callbacks(`function`(:`void`) `request_ok`, `function`(:`void`) `request_fail`, `mixed` ... `extra`)`
        ``Protocols.HTTP.Query` async_request(`string` `server`, `int` `port`, `string` `query`)`
        ``Protocols.HTTP.Query` async_request(`string` `server`, `int` `port`, `string` `query`, `mapping` `headers`, `string`|`void` `data`)`

      Description

        Setup and run an asynchronous request, otherwise similar to `thread_request()`.

        `request_ok`(Protocols.HTTP.Query httpquery,...extra args) will be called when connection is complete, and headers are parsed.

        `request_fail`(Protocols.HTTP.Query httpquery,...extra args) is called if the connection fails.

      Returns

        Returns the called object

      Method cast

        `(`array`)Protocols.HTTP.Query()`

      Returns

        Array
        ``mapping` `0`` | Headers
        ``string` `1`` | Data
        ``string` `2`` | Protocol
        ``int` `3`` | Status
        ``string` `4`` | Status description

      Method cast

        `(`mapping`)Protocols.HTTP.Query()`

      Returns

        The header mapping ORed with the following mapping.

        ``"protocol"` : `string`` | The protocol.
        ``"status"` : `int`` | The status code.
        ``"status_desc"` : `string`` | The status description.
        ``"data"` : `string`` | The returned data.

      Method cast

        `(`string`)Protocols.HTTP.Query()`

      Description

        Gives back the answer as a string.

      Method close

        ``void` close()`

      Description

        Close all associated file descriptors.

      Method data

        ``string` data(`int`|`void` `max_length`)`

      Description

        Gives back the data as a string.

      Method datafile

        ``Protocols.HTTP.Query.PseudoFile` datafile()`

      Description

        Gives back a pseudo-file object, with the methods `read()` and `close()`. This could be used to copy the file to disc at a proper tempo.

        `datafile()` doesn't give the complete request, just the data.

      See also

        `file()`

      Method downloaded_bytes

        ``int` downloaded_bytes()`

      Description

        Gives back the number of downloaded bytes.

      Variable errno

        ``int` Protocols.HTTP.Query.errno`

      Description

        Errno copied from the connection or simulated for async operations.

      Note

        In Pike 7.8 and earlier hardcoded Linux values were used in async operations, 110 instead of `System.ETIMEDOUT` and 113 instead of `System.EHOSTUNREACH`.

      Method file

        ``Protocols.HTTP.Query.PseudoFile` file()`
        ``Protocols.HTTP.Query.PseudoFile` file(`mapping` `newheaders`, `void`|`mapping` `removeheaders`)`

      Description

        Gives back a pseudo-file object, with the methods `read()` and `close()`. This could be used to copy the file to disc at a proper tempo.

        `newheaders`, `removeheaders` is applied as: `(oldheaders|newheaders))-removeheaders` Make sure all new and remove-header indices are lower case.

      See also

        `datafile()`

      Variable headers

        ``mapping` Protocols.HTTP.Query.headers`

      Description

        Headers as a mapping. All header names are in lower case, for convinience.

      Variable host
      Variable real_host
      Variable port

        ``string` Protocols.HTTP.Query.host`
        ``string` Protocols.HTTP.Query.real_host`
        ``int` Protocols.HTTP.Query.port`

      Description

        Connected host and port.

        Used to detect whether keep-alive can be used.

      Variable hostname_cache

        ``mapping` Protocols.HTTP.Query.hostname_cache`

      Description

        Set this to a global mapping if you want to use a cache, prior of calling *request().

      Variable ok

        ``int` Protocols.HTTP.Query.ok`

      Description

        Tells if the connection is successfull.

      Variable protocol

        ``string` Protocols.HTTP.Query.protocol`

      Description

        Protocol string, ie `"HTTP/1.0"`.

      Variable status
      Variable status_desc

        ``int` Protocols.HTTP.Query.status`
        ``string` Protocols.HTTP.Query.status_desc`

      Description

        Status number and description (eg `200` and `"ok"`).

      Method thread_request

        ``Protocols.HTTP.Query` thread_request(`string` `server`, `int` `port`, `string` `query`)`
        ``Protocols.HTTP.Query` thread_request(`string` `server`, `int` `port`, `string` `query`, `mapping` `headers`, `void`|`string` `data`)`

      Description

        Create a new query object and begin the query.

        The query is executed in a background thread; call ``()` in the object to wait for the request to complete.

        `query` is the first line sent to the HTTP server; for instance `"GET /index.html HTTP/1.1"`.

        `headers` will be encoded and sent after the first line, and `data` will be sent after the headers.

      Returns

        Returns the called object.

      Method timed_async_fetch

        ``void` timed_async_fetch(`function`(`object`, `mixed` ... :`void`) `ok_callback`, `function`(`object`, `mixed` ... :`void`) `fail_callback`, `mixed` ... `extra`)`

      Description

        Like `async_fetch()`, except with a timeout and a corresponding fail callback function.

      See also

        `async_fetch()`, `async_request()`, `set_callbacks()`

      Method total_bytes

        ``int` total_bytes()`

      Description

        Gives back the size of a file if a content-length header is present and parsed at the time of evaluation. Otherwise returns -1.

      Method unicode_data

        ``string` unicode_data()`

      Description

        Gives back data, but decoded according to the content-type character set.

      See also

        `data`

      ## Class Protocols.HTTP.Query.PseudoFile

        Description

          Minimal simulation of a `Stdio.File` object.

          Objects of this class are returned by `file()` and `datafile()`.

        Note

          Do not attempt further queries using this `Query` object before having read all data.

        Method close

          ``void` close()`

        Method read

          ``string` read(`int` `n`, `bool`|`void` `not_all`)`

    ## Class Protocols.HTTP.Session

      Method async_get_url
      Method async_put_url
      Method async_delete_url
      Method async_post_url

        ``Request` async_get_url(`URL` `url`, `void`|`mapping` `query_variables`, `function`(:`void`) `callback_headers_ok`, `function`(:`void`) `callback_data_ok`, `function`(:`void`) `callback_fail`, `mixed` ... `callback_arguments`)`
        ``Request` async_put_url(`URL` `url`, `void`|`string` `file`, `void`|`mapping` `query_variables`, `function`(:`void`) `callback_headers_ok`, `function`(:`void`) `callback_data_ok`, `function`(:`void`) `callback_fail`, `mixed` ... `callback_arguments`)`
        ``Request` async_delete_url(`URL` `url`, `void`|`mapping` `query_variables`, `function`(:`void`) `callback_headers_ok`, `function`(:`void`) `callback_data_ok`, `function`(:`void`) `callback_fail`, `mixed` ... `callback_arguments`)`
        ``Request` async_post_url(`URL` `url`, `mapping` `query_variables`, `function`(:`void`) `callback_headers_ok`, `function`(:`void`) `callback_data_ok`, `function`(:`void`) `callback_fail`, `mixed` ... `callback_arguments`)`

      Description

        Sends a HTTP GET, POST, PUT or DELETE request to the server in the URL asynchroneously, and call the corresponding callbacks when result arrives (or not). The callbacks will receive the created Request object as first argument, then the given `callback_arguments`, if any.

        `callback_headers_ok` is called when the HTTP request has received headers.

        `callback_data_ok` is called when the HTTP request has been received completely, data and all.

        `callback_fail` is called when the HTTP request has failed, on a TCP/IP or DNS level, or has received a forced timeout.

        The created Request object is returned.

      Method encode_cookies
      Method decode_cookies

        ``string` encode_cookies()`
        ``void` decode_cookies(`string` `data`, `void` `no_clear`)`

      Description

        Dump all cookies to a string and read them back. This is useful to store cookies in between sessions (on disk, for instance). `decode_cookies` will throw an error upon parse failures. Also note, `decode_cookies` will clear out any previously learned cookies from the `Session` object, unless no_clear is given and true.

      Variable default_headers

        ``mapping` Protocols.HTTP.Session.default_headers`

      Description

        Default HTTP headers.

      Method get_url
      Method post_url
      Method put_url
      Method delete_url

        ``Request` get_url(`URL` `url`, `void`|`mapping` `query_variables`)`
        ``Request` post_url(`URL` `url`, `mapping`|`string` `query_variables`)`
        ``Request` put_url(`URL` `url`, `string` `file`, `void`|`mapping` `query_variables`)`
        ``Request` delete_url(`URL` `url`, `void`|`mapping` `query_variables`)`

      Description

        Sends a HTTP GET, POST, PUT or DELETE request to the server in the URL and returns the created and initialized `Request` object. 0 is returned upon failure.

      Variable follow_redirects

        ``int` Protocols.HTTP.Session.follow_redirects`

      Description

        The number of redirects to follow, if any. This is the default to the created Request objects.

        A redirect automatically turns into a GET request, and all header, query, post or put information is dropped.

        Default is 20 redirects. A negative number will mean infinity.

      Bugs

        Loops will currently not be detected, only the limit works to stop loops.

      See also

        `Request.follow_redirects`

      Method get_cookies

        ``array`(`string`) get_cookies(`Standards.URI`|`SessionURL` `for_url`, `void`|`bool` `no_delete`)`

      Description

        Get the cookies that we should send to this server, for this url. They are presented in the form suitable for HTTP headers (as an array). This will also take in count expiration of cookies, and delete expired cookies from the `Session` unless `no_delete` is true.

      Method get_url_nice
      Method get_url_data
      Method post_url_nice
      Method post_url_data

        ``array`(`string`) get_url_nice(`URL` `url`, `mapping` `query_variables`)`
        ``string` get_url_data(`URL` `url`, `mapping` `query_variables`)`
        ``array`(`string`) post_url_nice(`URL` `url`, `mapping`|`string` `query_variables`)`
        ``string` post_url_data(`URL` `url`, `mapping`|`string` `query_variables`)`

      Description

        Returns an array of `({content_type,data})` and just the data string respective, after calling the requested server for the information. `0` is returned upon failure.

        post* is similar to the `get_url()` class of functions, except that the query variables is sent as a POST request instead of as a GET.

      Method give_me_connection

        ``Query` give_me_connection(`Standards.URI` `url`)`

      Description

        Request a `Query` object suitable to use for the given URL. This may be a reused object from a keep-alive connection.

      Variable hostname_cache

        ``mapping` Protocols.HTTP.Session.hostname_cache`

      Description

        Cache of hostname to IP lookups. Given to and used by the `Query` objects.

      Variable maximum_connection_reuse

        ``int` Protocols.HTTP.Session.maximum_connection_reuse`

      Description

        Maximum times a connection is reused. Defaults to 1000000. <2 means no reuse at all.

      Variable maximum_connections_per_server

        ``int` Protocols.HTTP.Session.maximum_connections_per_server`

      Description

        Maximum number of connections to the same server. Used only by async requests. Defaults to 10 connections.

      Variable maximum_total_connections

        ``int` Protocols.HTTP.Session.maximum_total_connections`

      Description

        Maximum total number of connections. Limits only async requests, and the number of kept-alive connections (live connections + kept-alive connections <= this number) Defaults to 50 connections.

      Method return_connection

        ``void` return_connection(`Standards.URI` `url`, `Query` `query`)`

      Description

        Return a previously used Query object to the keep-alive storage. This function will determine if the given object is suitable to keep or not by checking status and headers.

      Method set_cookie

        ``void` set_cookie(`Cookie` `cookie`, `Standards.URI` `who`)`

      Description

        Set a cookie. The cookie will be checked against current security levels et al, using the parameter `who`. If `who` is zero, no security checks will be performed.

      Method set_http_cookie

        ``void` set_http_cookie(`string` `cookie`, `Standards.URI` `at`)`

      Description

        Parse and set a cookie received in the HTTP protocol. The cookie will be checked against current security levels et al.

      Variable time_to_keep_unused_connections

        ``int`|`float` Protocols.HTTP.Session.time_to_keep_unused_connections`

      Description

        The time to keep unused connections in seconds. Set to zero to never save any kept-alive connections. (Might be good in a for instance totaly synchroneous script that keeps the backend thread busy and never will get call_outs.) Defaults to 10 seconds.

      ## Class Protocols.HTTP.Session.Request

        Description

          Request

        Variable con

          ``Query` Protocols.HTTP.Session.Request.con`

        Description

          Raw connection object

        Variable cookie_encountered

          ``function`(`string`, `Standards.URI`:`mixed`) Protocols.HTTP.Session.Request.cookie_encountered`

        Description

          Cookie callback. When a request is performed, the result is checked for cookie changes and additions. If a cookie is encountered, this function is called. Default is to call `set_http_cookie` in the `Session` object.

        Method destroy

          ``void` destroy()`

        Description

          `destroy` is called when an object is destructed. But since this clears the HTTP connection from the Request object, it can also be used to reuse a `Request` object.

        Method do_async

          ``Request` do_async(`array`(`string`|`int`|`mapping`) `args`)`

        Description

          Start a request asyncroneously. It will perform in the background using callbacks (make sure the backend thread is free). Call `set_callbacks` to setup the callbacks. Get arguments from `prepare_method`.

        Returns

          The called object.

        See also

          `set_callbacks`, `prepare_method`, `do_sync`, `do_thread`

        Method do_sync

          ``Request` do_sync(`array`(`string`|`int`|`mapping`) `args`)`

        Description

          Perform a request synchronously. Get arguments from `prepare_method`.

        Returns

          0 upon failure, this object upon success

        See also

          `prepare_method`, `do_async`, `do_thread`

        Method do_thread

          ``Request` do_thread(`array`(`string`|`int`|`mapping`) `args`)`

        Description

          Start a request in the background, using a thread. Call `wait` to wait for the thread to finish. Get arguments from `prepare_method`.

        Returns

          The called object.

        See also

          `prepare_method`, `do_sync`, `do_async`, `wait`

        Note

          `do_thread` does not rerun redirections automatically

        Variable follow_redirects

          ``int` Protocols.HTTP.Session.Request.follow_redirects`

        Description

          Number of redirects to follow; the request will perform another request if the HTTP answer is a 3xx redirect. Default from the parent `Session.follow_redirects`.

          A redirect automatically turns into a GET request, and all header, query, post or put information is dropped.

        Bugs

          Loops will currently not be detected, only the limit works to stop loops.

        Method prepare_method

          ``array`(`string`|`int`|`mapping`) prepare_method(`string` `method`, `URL` `url`, `void`|`mapping` `query_variables`, `void`|`mapping` `extra_headers`, `void`|`string` `data`)`

        Description

          Prepares the HTTP Query object for the connection, and returns the parameters to use with `do_sync`, `do_async` or `do_thread`.

          This method will also use cookie information from the parent `Session`, and may reuse connections (keep-alive).

        Method set_callbacks

          ``void` set_callbacks(`function`(`mixed` ... :`mixed`) `headers`, `function`(`mixed` ... :`mixed`) `data`, `function`(`mixed` ... :`mixed`) `fail`, `mixed` ... `callback_arguments`)`

        Description

          Setup callbacks for async mode, `headers` will be called when the request got connected, and got data headers; `data` will be called when the request got the amount of data it's supposed to get and `fail` is called whenever the request failed.

          Note here that an error message from the server isn't considered a failure, only a failed TCP connection.

        Variable url_requested

          ``Standards.URI` Protocols.HTTP.Session.Request.url_requested`

        Description

          URL requested (set by prepare_method). This will update according to followed redirects.

        Method wait

          ``Request` wait()`

        Description

          Wait for the request thread to finish.

        Returns

          0 upon failure, or the called object upon success.

        See also

          `do_thread`

      ## Class Protocols.HTTP.Session.SessionURL

        Description

          Class to store URL+referer

        Method create

          `Protocols.HTTP.Session.SessionURL Protocols.HTTP.Session.SessionURL(`URL` `uri`, `URL` `base_uri`, `URL` `_referer`)`

        Description

          instantiate a SessionURL object; when fed to Protocols.HTTP.Session calls, will add referer to the HTTP handshaking variables

        Inherit URI

          `inherit Standards.URI : URI`

        Variable referer

          ``URL` Protocols.HTTP.Session.SessionURL.referer`

        Description

          the referer to this URL

    ## Module Protocols.HTTP.Server

      Constant HeaderParser

        ``constant` Protocols.HTTP.Server.`HeaderParser``

      Description

        Fast HTTP header parser.

      Method extension_to_type

        ``string` extension_to_type(`string` `extension`)`

      Description

        Looks up the file extension in a table to return a suitable MIME type.

      Method filename_to_type

        ``string` filename_to_type(`string` `filename`)`

      Description

        Looks up the file extension in a table to return a suitable MIME type.

      Method http_date

        ``string` http_date(`int` `time`)`

      Description

        Makes a time notification suitable for the HTTP protocol.

      Parameter `time`

        The time in seconds since the 00:00:00 UTC, January 1, 1970

      Returns

        The date in the HTTP standard date format. Example : Thu, 03 Aug 2000 05:40:39 GMT

      Method http_decode_date

        ``int` http_decode_date(`string` `data`)`

      Description

        Decode a HTTP date to seconds since 1970 (UTC)

      Returns

        zero (UNDEFINED) if the given string isn't a HTTP date

      Constant http_decode_string

        ``constant` Protocols.HTTP.Server.`http_decode_string``

      Method http_decode_urlencoded_query

        ``mapping`(`string`:`string`|`array`(`string`)) http_decode_urlencoded_query(`string` `query`, `void`|`mapping` `dest`)`

      Description

        Decodes an URL-encoded query into a mapping.

      ## Class Protocols.HTTP.Server.Port

        Description

          The simplest server possible. Binds a port and calls a callback with `request_program` objects.

        Method close

          ``void` close()`

        Description

          Closes the HTTP port.

        Method create

          `Protocols.HTTP.Server.Port Protocols.HTTP.Server.Port(`function`(`.Request`:`void`) `callback`)`
          `Protocols.HTTP.Server.Port Protocols.HTTP.Server.Port(`function`(`.Request`:`void`) `callback`, `int` `portno`, `void`|`string` `interface`)`

        Variable request_program

          ``object`|`function`(:`void`)|`program` Protocols.HTTP.Server.Port.request_program`

      ## Class Protocols.HTTP.Server.Request

        Variable body_raw

          ``string` Protocols.HTTP.Server.Request.body_raw`

        Description

          raw unparsed body of the request (`raw` minus request line and headers)

        Variable connection_timeout_delay

          ``int` Protocols.HTTP.Server.Request.connection_timeout_delay`

        Description

          connection timeout, delay until connection is closed while waiting for the correct headers:

        Variable cookies

          ``mapping`(`string`:`string`) Protocols.HTTP.Server.Request.cookies`

        Description

          cookies set by client

        Variable full_query

          ``string` Protocols.HTTP.Server.Request.full_query`

        Description

          full resource requested, including attached GET query

        Method get_ip

          ``string` get_ip()`

        Description

          Return the IP address that originated the request, or 0 if the IP address could not be determined. In the event of an error, `my_fd``->errno()` will be set.

        Variable misc

          ``mapping` Protocols.HTTP.Server.Request.misc`

        Description

          external use only

        Variable my_fd

          ``Stdio.NonblockingStream` Protocols.HTTP.Server.Request.my_fd`

        Description

          The socket that this request came in on.

        Variable not_query

          ``string` Protocols.HTTP.Server.Request.not_query`

        Description

          resource requested minus any attached query

        Variable protocol

          ``string` Protocols.HTTP.Server.Request.protocol`

        Description

          request protocol and version, eg. HTTP/1.0

        Variable query

          ``string` Protocols.HTTP.Server.Request.query`

        Description

          query portion of requested resource, starting after the first "?"

        Variable raw

          ``string` Protocols.HTTP.Server.Request.raw`

        Description

          raw unparsed full request (headers and body)

        Variable request_headers

          ``mapping`(`string`:`string`|`array`(`string`)) Protocols.HTTP.Server.Request.request_headers`

        Description

          all headers included as part of the HTTP request, ie content-type.

        Variable request_raw

          ``string` Protocols.HTTP.Server.Request.request_raw`

        Description

          full request line (`request_type` + `full_query` + `protocol`)

        Variable request_type

          ``string` Protocols.HTTP.Server.Request.request_type`

        Description

          HTTP request method, eg. POST, GET, etc.

        Method response_and_finish

          ``void` response_and_finish(`mapping` `m`, `function`(:`void`)|`void` `_log_cb`)`

        Description

          return a properly formatted response to the HTTP client

        Parameter `m`

          Contains elements for generating a response to the client.

          ``"data"` : `string`` | Data to be returned to the client.
          ``"file"` : `object`` | File object, the contents of which will be returned to the client.
          ``"error"` : `int`` | HTTP error code
          ``"length"` : `int`` | length of content returned. If file is provided, size bytes will be returned to client.
          ``"modified"` : `string`` | contains optional modification date.
          ``"type"` : `string`` | contains optional content-type
          ``"extra_heads"` : `mapping`` | contains a mapping of additional headers to be returned to client.
          ``"server"` : `string`` | contains the server identification header.

        Variable send_timeout_delay

          ``int` Protocols.HTTP.Server.Request.send_timeout_delay`

        Description

          send timeout (no activity for this period with data in send buffer) in seconds, default is 180

        Method sent_data

          ``int` sent_data()`

        Description

          Returns the amount of data sent.

        Variable variables

          ``mapping`(`string`:`string`|`array`(`string`)) Protocols.HTTP.Server.Request.variables`

        Description

          all variables included as part of a GET or POST request.

      ## Class Protocols.HTTP.Server.SSLPort

        Description

          A very simple SSL server. Binds a port and calls a callback with `request_program` objects.

        Method create

          `Protocols.HTTP.Server.SSLPort Protocols.HTTP.Server.SSLPort(`function`(`Request`:`void`) `callback`, `void`|`int` `port`, `void`|`string` `interface`, `void`|`string`|`Crypto.Sign.State` `key`, `void`|`string`|`array`(`string`) `certificate`, `void`|`int` `share`)`

        Description

          Create a HTTPS (HTTP over SSL) server.

        Parameter `callback`

          The function run when a request is received. takes one argument of type `Request`.

        Parameter `port`

          The port number to bind to, defaults to 443.

        Parameter `interface`

          The interface address to bind to.

        Parameter `key`

          An optional SSL secret key, provided in binary format, such as that created by `Standards.PKCS.RSA.private_key()`.

        Parameter `certificate`

          An optional SSL certificate or chain of certificates with the host certificate first, provided in binary format.

        Parameter `share`

          If true, the connection will be shared if possible. See `Stdio.Port.bind` for more information

        Inherit Port

          `inherit SSL.Port : Port`

        Method new_connection

          ``protected` `void` new_connection()`

        Description

          The port accept callback

        Variable request_program

          ``object`|`function`(:`void`)|`program` Protocols.HTTP.Server.SSLPort.request_program`

        Method set_certificate

          ``__deprecated__` `void` set_certificate(`string`|`array`(`string`) `certificate`)`

        Deprecated

          Replaced by `add_cert`.

        Method set_key

          ``__deprecated__` `void` set_key(`string` `skey`)`

        Deprecated

          Replaced by `add_cert`.

  ## Module SSL

    Description

      Secure Socket Layer (SSL) version 3.0 and Transport Layer Security (TLS) versions 1.0 - 1.2.

      RFC 2246 (TLS 1.0): "The primary goal of the TLS Protocol is to provide privacy and data integrity between two communicating applications."

      The classes that typical users need to use are

      `File`

        This is an object that attempts to behave as a `Stdio.File` as much as possible.

      `Port`

        This is an object that attempts to behave as a `Stdio.Port` as much as possible, with `Port()->accept()` returning `File` objects.

      `Context`

        The configurated context for the `File`.

      `Constants.CertificatePair`

        A class for keeping track of certificate chains and their private keys.

      The `Constants` module also contains lots of constants that are used by the various APIs, as well as functions for formatting the constants for output.

    See also

      `File`, `Port`, `Context`, `Constants.CertificatePair`, `Constants`

    ## Class SSL.Alert

      Description

        Alert packet.

      Method create

        `SSL.Alert SSL.Alert(`int(1..2)` `level`, `int(8bit)` `description`, `ProtocolVersion` `version`, `string`|`void` `message`)`

      Inherit Packet

        `inherit .Packet : Packet`

      Description

        Based on the base `Packet`.

    ## Class SSL.ClientConnection

      Description

        Client-side connection state.

      Variable client_cert_types
      Variable client_cert_distinguished_names

        ``array`(`int`) SSL.ClientConnection.client_cert_types`
        ``array`(`string(8bit)`) SSL.ClientConnection.client_cert_distinguished_names`

      Description

        A few storage variables for client certificate handling on the client side.

      Method client_hello

        ``Packet` client_hello(`string(8bit)`|`void` `server_name`)`

      Method create

        `SSL.ClientConnection SSL.ClientConnection(`Context` `ctx`, `string(8bit)`|`void` `server_name`, `Session`|`void` `session`)`

      Description

        Initialize a new `ClientConnection`.

      Parameter `ctx`

        `Context` to use.

      Parameter `server_name`

        Optional host name of the server.

      Parameter `session`

        Optional `Session` to resume.

      Method handle_handshake

        ``int(-1..1)` handle_handshake(`int` `type`, `string(8bit)` `data`, `string(8bit)` `raw`)`

      Description

        Do handshake processing. Type is one of HANDSHAKE_*, data is the contents of the packet, and raw is the raw packet received (needed for supporting SSLv2 hello messages).

        This function returns 0 if handshake is in progress, 1 if handshake is finished, and -1 if a fatal error occurred. It uses the send_packet() function to transmit packets.

      Inherit Connection

        `inherit Connection : Connection`

      Method send_renegotiate

        ``void` send_renegotiate()`

      Description

        Renegotiate the connection (client initiated).

        Sends a `client_hello` to force a new round of handshaking.

    ## Class SSL.Connection

      Description

        SSL.Connection keeps the state relevant for a single SSL connection. This includes the `Context` object (which doesn't change), various buffers, the `Session` object (reused or created as appropriate), and pending read and write states being negotiated.

        Each connection will have two sets of read and write `State`s: The current read and write states used for encryption, and pending read and write states to be taken into use when the current keyexchange handshake is finished.

        This object is also responsible for managing incoming and outgoing packets. Outgoing packets are stored in queue objects and sent in priority order.

      Note

        This class should never be created directly, instead one of the classes that inherits it should be used (ie either `ClientConnection` or `ServerConnection`) depending on whether this is to be a client-side or server-side connection. These in turn are typically created by `File()->create()`.

      See also

        `ClientConnection`, `ServerConnection`, `Context`, `Session`, `File`, `State`

      Variable application_protocol

        ``string(8bit)` SSL.Connection.application_protocol`

      Description

        Selected ALPN (RFC 7301) protocol (if any).

      Note

        Note that this is a connection property, and needs to be renegotiated on session resumption.

      Variable client_random
      Variable server_random

        ``string(8bit)` SSL.Connection.client_random`
        ``string(8bit)` SSL.Connection.server_random`

      Description

        Random cookies, sent and received with the hello-messages.

      Method create

        `SSL.Connection SSL.Connection(`Context` `ctx`)`

      Description

        Initialize the connection state.

      Parameter `ctx`

        The context for the connection.

      Method describe_state

        ``string` describe_state()`

      Description

        Returns a string describing the current connection state.

      Method got_data

        ``string(8bit)`|`int` got_data(`string(8bit)` `data`)`

      Description

        Main receive handler.

      Parameter `data`

        String of data received from the peer.

      Returns

        Returns one of:

        ``string(0..0)`` | Returns an empty string if there's neither application data nor errors (eg during the initial handshake).
        ``string(8bit)`` | Returns a string of received application data.
        ``int(1..1)`` | Returns `1` if the peer has closed the connection.

        ``int(-1..-1)``

        Returns `-1` if an error has occurred.

        These are the main cases of errors:

        - There was a low-level protocol communications failure (the data didn't look like an SSL packet), in which case the alert_callback will be called with the raw packet data. This can eg be used to detect HTTP clients connecting to an HTTPS server and similar.

        - The peer has sent an `Alert` packet, and `handle_alert()` for it has returned -1.

        - The peer has sent an unsupported/illegal sequence of packets, in which case a suitable `Alert` will have been generated and queued for sending to the peer.

        This function is intended to be called from an i/o read callback.

      Method handle_alert

        ``int(-1..1)` handle_alert(`int` `level`, `int` `description`)`

      Description

        Handle an alert received from the peer.

      Parameter `level`

        Alert level; either `ALERT_warning` or `ALERT_fatal`.

      Parameter `description`

        Alert description code; one of `indices(SSL.Constants.ALERT_descriptions)`.

      Returns

        ``int(-1..-1)`` | Returns `-1` if a fatal error occurred and processing should stop.
        ``int(0..0)`` | Returns `0` if processing can continue.
        ``int(1..1)`` | Returns `1` if connection should close.

      Method handle_handshake

        ``int(-1..1)` handle_handshake(`int` `type`, `string(8bit)` `data`, `string(8bit)` `raw`)`

      Description

        Do handshake processing. Type is one of HANDSHAKE_*, data is the contents of the packet, and raw is the raw packet received (needed for supporting SSLv2 hello messages).

        This function returns 0 if handshake is in progress, 1 if handshake is finished, and -1 if a fatal error occurred. It uses the send_packet() function to transmit packets.

      Variable ke

        ``.Cipher.KeyExchange` SSL.Connection.ke`

      Description

        The active `Cipher.KeyExchange` (if any).

      Method query_write_queue_size

        ``int` query_write_queue_size()`

      Description

        Returns the number of packets queued for writing.

      Returns

        Returns the number of times `to_write()` can be called before it stops returning non-empty strings.

      Method recv_packet

        ``protected` `Packet` recv_packet(`string(8bit)` `data`)`

      Description

        Low-level receive handler. Returns a packet, an alert, or zero if more data is needed to get a complete packet.

      Method send_close

        ``void` send_close()`

      Description

        Initiate close.

      Method send_packet

        ``void` send_packet(`Packet` `packet`, `int`|`void` `priority`)`

      Description

        Queues a packet for write. Handshake and and change cipher must use the same priority, so must application data and close_notifies.

      Method send_renegotiate

        ``void` send_renegotiate()`

      Description

        Renegotiate the connection.

      Method send_streaming_data

        ``int` send_streaming_data(`string(8bit)` `data`)`

      Description

        Send an application data packet. If the data block is too large then as much as possible of the beginning of it is sent. The size of the sent data is returned.

      Variable sent

        ``int` SSL.Connection.sent`

      Description

        Number of application data bytes sent by us.

      Method set_alert_callback

        ``void` set_alert_callback(`function`(`object`, `int`|`object`, `string`:`void`) `callback`)`

      Description

        Called with alert object, sequence number of bad packet, and raw data as arguments, if a bad packet is received.

        Can be used to support a fallback redirect https->http.

      Variable state

        ``ConnectionState` SSL.Connection.state`

      Description

        Bitfield with the current connection state.

      Method to_write

        ``string`|`int` to_write()`

      Description

        Extracts data from the packet queues. Returns a string of data to be written, "" if there are no pending packets, 1 of the connection is being closed politely, and -1 if the connection died unexpectedly.

        This function is intended to be called from an i/o write callback.

      See also

        `query_write_queue_size()`, `send_streaming_data()`.

    ## Class SSL.Context

      Description

        Keeps the state that is shared by all SSL-connections on a client, or for one port on a server. It includes policy configuration, the server or client certificate(s), the corresponding private key(s), etc. It also includes the session cache.

        The defaults are usually suitable for a client, but for a server some configuration is necessary.

        Typical use is to:

        - Call `add_cert()` with the certificates belonging to the server or client. Note that clients often don't have or need any certificates, and also that certificate-less server operation is possible, albeit discouraged and not enabled by default.

          Suitable self-signed certificates can be created with `Standards.X509.make_selfsigned_certificate()`.

        - Optionally call `get_suites()` to get a set of cipher_suites to assign to `preferred_suites`. This is only needed if the default set of suites from `get_suites(128, 1)` isn't satisfactory.

        The initialized `Context` object is then passed to `File()->create()` or used as is embedded in `Port`.

      See also

        `File`, `Port`, `Standards.X509`

      Method add_cert

        ``void` add_cert(`Crypto.Sign.State` `key`, `array`(`string(8bit)`) `certs`, `array`(`string(8bit)`)|`void` `extra_name_globs`)`
        ``variant` `void` add_cert(`string(8bit)` `key`, `array`(`string(8bit)`) `certs`, `array`(`string(8bit)`)|`void` `extra_name_globs`)`
        ``variant` `void` add_cert(`CertificatePair` `cp`)`

      Description

        Add a certificate.

        This function is used on both servers and clients to add a key and chain of certificates to the set of certificate candidates to use in `find_cert()`.

        On a server these are used in the normal initial handshake, while on a client they are only used if a server requests client certificate authentication.

      Parameter `key`

        Private key matching the first certificate in `certs`.

        Supported key types are currently:

        ``Crypto.RSA.State`` | Rivest-Shamir-Adelman.
        ``Crypto.DSA.State`` | Digital Signing Algorithm.
        ``Crypto.ECC.Curve.ECDSA`` | Elliptic Curve Digital Signing Algorithm.

        This key MUST match the public key in the first certificate in `certs`.

      Parameter `certs`

        A chain of X509.v1 or X509.v3 certificates, with the local certificate first and root-most certificate last.

      Parameter `extra_name_globs`

        Further SNI globs (than the ones in the first certificate), that this certificate should be selected for. Typically used to set the default certificate(s) by specifying `({ "*" })`.

        The SNI globs are only relevant for server-side certificates.

      Parameter `cp`

        An alternative is to send an initialized `CertificatePair`.

      Throws

        The function performs various validations of the `key` and `certs`, and throws errors if the validation fails.

      See also

        `find_cert()`

      Variable advertised_protocols

        ``array`(`string(8bit)`) SSL.Context.advertised_protocols`

      Description

        List of advertised protocols using using TLS application level protocol negotiation.

      Method alert_factory

        ``Alert` alert_factory(`SSL.Connection` `con`, `int` `level`, `int` `description`, `ProtocolVersion` `version`, `string`|`void` `message`, `mixed`|`void` `trace`)`

      Description

        Alert factory.

        This function may be overloaded to eg obtain logging of generated alerts.

      Parameter `con`

        Connection which caused the alert.

      Parameter `level`

        Level of alert.

      Parameter `description`

        Description code for the alert.

      Parameter `message`

        Optional log message for the alert.

      Note

        Not all alerts are fatal, and some (eg `ALERT_close_notify`) are used during normal operation.

      Variable auth_level

        ``int` SSL.Context.auth_level`

      Description

        Policy for client authentication. One of `SSL.Constants.AUTHLEVEL_none`, `SSL.Constants.AUTHLEVEL_ask` and `SSL.Constants.AUTHLEVEL_require`.

      Variable certificates

        ``__deprecated__` `array`(`string(8bit)`) SSL.Context.certificates`

      Description

        Getting

        The server's certificate, or a chain of X509.v3 certificates, with the server's certificate first and root certificate last.

        Compatibility, don't use.

      Deprecated

        Replaced by `find_cert`.

      See also

        ``rsa`, `find_cert()`

        Setting

        The server's certificate, or a chain of X509.v3 certificates, with the server's certificate first and root certificate last.

        Compatibility, don't use.

      Deprecated

        Replaced by `find_cert`.

      See also

        ``rsa`, `find_cert()`

      Variable client_certificates

        ``__deprecated__` `array`(`array`(`string(8bit)`)) SSL.Context.client_certificates`

      Description

        Getting

        The client's certificate, or a chain of X509.v3 certificates, with the client's certificate first and root certificate last.

        Compatibility, don't use.

      Deprecated

        Replaced by `find_cert`.

      See also

        ``rsa`, `find_cert()`

        Setting

        The client's certificate, or a chain of X509.v3 certificates, with the client's certificate first and root certificate last.

        Compatibility, don't use.

      Deprecated

        Replaced by `find_cert`.

      See also

        ``rsa`, `find_cert()`

      Variable client_rsa

        ``__deprecated__` `Crypto.RSA.State` SSL.Context.client_rsa`

      Description

        Getting

        The clients RSA private key.

        Compatibility, don't use.

      Deprecated

        Replaced by `find_cert`.

      See also

        ``certificates`, `find_cert()`

        Setting

        The clients RSA private key.

        Compatibility, don't use.

      Deprecated

        Replaced by `find_cert`.

      See also

        ``certificates`, `find_cert()`

      Method configure_suite_b

        ``void` configure_suite_b(`int(128..)`|`void` `min_keylength`, `int(0..)`|`void` `strictness_level`)`

      Description

        Configure the context for Suite B compliant operation.

        This restricts the context to the cipher suites specified by RFC 6460 in strict mode.

        Additional suites may be enabled, but they will only be selected if a Suite B suite isn't available.

      Parameter `min_keylength`

        Minimum supported key length in bits. Either `128` or `192`.

      Parameter `strictness_level`

        Allow additional suites.

        ``(2..)`` | Strict mode. Allow only the Suite B suites from RFC 6460 and TLS 1.2.
        ``1`` | Transitional mode. Also allow the transitional suites from RFC 5430 for use with TLS 1.0 and 1.1.
        ``0`` | Permissive mode (default). Also allow other suites that conform to the minimum key length.

      Note

        This function is only present when Suite B compliant operation is possible (ie both elliptic curves and GCM are available).

      Note

        Note also that for Suite B server operation compliant certificates need to be added with `add_cert()`.

      See also

        `get_suites()`

      Method decode_ticket

        ``Session` decode_ticket(`string(8bit)` `ticket`)`

      Description

        Decode a session ticket and return the corresponding session if valid or zero if invalid.

      Note

        The default implementation just calls `lookup_session()`.

        Override this function (and `encode_ticket()`) to implement server-side state-less session resumption.

      See also

        `encode_ticket()`, `lookup_session()`

      Variable dh_groups

        ``array`(`Crypto.DH.Parameters`) SSL.Context.dh_groups`

      Description

        Supported DH groups for DHE key exchanges, in order of preference. Defaults to FFDHE-2048.

      Method dhe_dss_mode

        ``__deprecated__` `void` dhe_dss_mode(`int(0..)`|`void` `min_keylength`)`

      Description

        Set `preferred_suites` to DSS based methods.

      Parameter `min_keylength`

        Minimum acceptable key length in bits.

      See also

        `rsa_mode()`, `filter_weak_suites()`

      Deprecated

        Replaced by `get_suites`.

      Variable dsa

        ``__deprecated__` `Crypto.DSA.State` SSL.Context.dsa`

      Description

        Getting

        Compatibility.

      Deprecated

        Replaced by `find_cert`.

        Setting

        Compatibility.

      Deprecated

        Replaced by `find_cert`.

      Variable ecc_curves

        ``array`(`int`) SSL.Context.ecc_curves`

      Description

        Supported elliptical curve cipher curves in order of preference.

      Method encode_ticket

        ``array`(`string(8bit)`|`int`) encode_ticket(`Session` `session`)`

      Description

        Generate a session ticket for a session.

      Note

        The default implementation just generates a random ticket and calls `record_session()` to store it.

        Over-ride this function (and `decode_ticket()`) to implement server-side state-less session resumption.

      Returns

        Array
        ``string(8bit)` `0`` | Non-empty string with the ticket.
        ``int` `1`` | Lifetime hint for the ticket.

      Note

        If the context signals that it does offer tickets via `offers_tickets()`, this function must offer an encoded ticket for the session as the connection may have signalled to the client that a ticket will be offered. However, tickets are not guaranteed to be actually usable, so if you cannot offer a ticket when you must, `"INVALID"` might be an option...

      See also

        `decode_ticket()`, `record_session()`, RFC 4507 section 3.3

      Variable encrypt_then_mac

        ``int` SSL.Context.encrypt_then_mac`

      Description

        Attempt to enable encrypt-then-mac mode.

      Method filter_weak_suites

        ``void` filter_weak_suites(`int` `min_keylength`)`

      Description

        Filter cipher suites from `preferred_suites` that don't have a key with an effective length of at least `min_keylength` bits.

      Method find_cert_domain

        ``array`(`CertificatePair`) find_cert_domain(`string(8bit)` `domain`)`

      Description

        Look up a suitable set of certificates for the specified domain. `UNDEFINED` if no certificate was found.

      Method find_cert_issuer

        ``array`(`CertificatePair`) find_cert_issuer(`array`(`string`) `ders`)`

      Description

        Look up a suitable set of certificates for the specified issuer. `UNDEFIEND` if no certificate was found.

      Method get_authorities

        ``array`(`string`) get_authorities()`

      Description

        Get the list of allowed authorities. See `set_authorities`.

      Method get_certificates

        ``array`(`CertificatePair`) get_certificates()`

      Description

        Returns a list of all server certificates added with `add_cert`.

      Method get_signature_algorithms

        ``array`(`array`(`int`)) get_signature_algorithms(`array`(`array`(`int`))|`void` `signature_algorithms`)`

      Description

        Get the (filtered) set of locally supported signature algorithms.

      See also

        `signature_algorithms`

      Method get_suites

        ``array`(`int`) get_suites(`int(-1..)`|`void` `min_keylength`, `int(0..2)`|`void` `ke_flags`, `multiset`(`int`)|`void` `blacklisted_ciphers`, `multiset`(`KeyExchangeType`)|`void` `blacklisted_kes`, `multiset`(`HashAlgorithm`)|`void` `blacklisted_hashes`, `multiset`(`CipherModes`)|`void` `blacklisted_ciphermodes`)`

      Description

        Get the prioritized list of supported cipher suites that satisfy the requirements.

      Parameter `min_keylength`

        Minimum supported effective keylength in bits. Defaults to `128`. Specify `-1` to enable null ciphers.

      Parameter `ke_mode`

        Level of protection for the key exchange.

        ``0`` | Require forward secrecy (ephemeral keys).
        ``1`` | Also allow certificate based key exchanges.
        ``2`` | Allow anonymous server key exchange. Note that this allows for man in the middle attacks.

      Parameter `blacklisted_ciphers`

        Multiset of ciphers that are NOT to be used.

      Parameter `blacklisted_kes`

        Multiset of key exchange methods that are NOT to be used.

      Parameter `blacklisted_hashes`

        Multiset of hash algoriths that are NOT to be used.

      Parameter `blacklisted_ciphermodes`

        Multiset of cipher modes that are NOT to be used.

      Note

        Note that the effective keylength may differ from the actual keylength for old ciphers where there are known attacks.

      Method get_trusted_issuers

        ``array`(`array`(`string`)) get_trusted_issuers()`

      Description

        Get the list of trusted issuers. See `set_trusted_issuers`.

      Variable heartbleed_probe

        ``bool` SSL.Context.heartbleed_probe`

      Description

        If set, the other peer will be probed for the heartbleed bug during handshake. If heartbleed is found the connection is closed with insufficient security fatal error.

      Variable long_rsa
      Variable short_rsa

        ``Crypto.RSA.State` SSL.Context.long_rsa`
        ``Crypto.RSA.State` SSL.Context.short_rsa`

      Description

        Temporary, non-certified, private keys, used for RSA key exchange in export mode. They are used as follows:

        `short_rsa` is a 512-bit RSA key used for the SSL 3.0 and TLS 1.0 export cipher suites.

        `long_rsa` is a 1024-bit RSA key to be used for the RSA_EXPORT1024 suites from draft-ietf-tls-56-bit-ciphersuites-01.txt.

        They have associated counters `short_rsa_counter` and `long_rsa_counter`, which are decremented each time the keys are used.

        When the counters reach zero, the corresponding RSA key is cleared, and a new generated on demand at which time the counter is reset.

      Variable long_rsa_counter
      Variable short_rsa_counter

        ``int` SSL.Context.long_rsa_counter`
        ``int` SSL.Context.short_rsa_counter`

      Description

        Counters for export RSA keys.

      Method lookup_session

        ``Session` lookup_session(`string` `id`)`

      Description

        Lookup a session identifier in the cache. Returns the corresponding session, or zero if it is not found or caching is disabled.

      Variable max_sessions

        ``int` SSL.Context.max_sessions`

      Description

        Maximum number of sessions to keep in the cache.

      Variable max_version

        ``ProtocolVersion` SSL.Context.max_version`

      Description

        The maximum supported protocol version.

        Defaults to `PROTOCOL_TLS_MAX`.

      Note

        This value should not be less than `min_version`.

      Variable min_version

        ``ProtocolVersion` SSL.Context.min_version`

      Description

        The minimum supported protocol version.

        Defaults to `PROTOCOL_TLS_1_0`.

      Note

        This value should not be greater than `max_version`.

      Method new_session

        ``Session` new_session()`

      Description

        Create a new session.

      Method offers_tickets

        ``bool` offers_tickets()`

      Description

        Signals if the context will offer a session ticket via `encode_ticket()`.

      Variable packet_max_size

        ``int` SSL.Context.packet_max_size`

      Description

        The maximum amount of data that is sent in each SSL packet by `File`. A value between 1 and `Constants.PACKET_MAX_SIZE`.

      Variable preferred_auth_methods

        ``array`(`int`) SSL.Context.preferred_auth_methods`

      Description

        For client authentication. Used only if auth_level is AUTH_ask or AUTH_require.

      Variable preferred_compressors

        ``array`(`int`) SSL.Context.preferred_compressors`

      Description

        Lists the supported compression algorithms in order of preference.

        Defaults to `({ COMPRESSION_null })` due to SSL attacks that target compression.

      Variable preferred_suites

        ``array`(`int`) SSL.Context.preferred_suites`

      Description

        Cipher suites we want to support, in order of preference, best first.

      Method purge_session

        ``void` purge_session(`Session` `s`)`

      Description

        Invalidate a session for resumption and remove it from the cache.

      Variable random

        ``function`(`int(0..)`:`string(8bit)`) SSL.Context.random`

      Description

        Used to generate random cookies for the hello-message. If we use the RSA keyexchange method, and this is a server, this random number generator is not used for generating the master_secret. By default set to `Crypto.Random.random_string`.

      Method record_session

        ``void` record_session(`Session` `s`)`

      Description

        Add a session to the cache (if caching is enabled).

      Variable require_trust

        ``int` SSL.Context.require_trust`

      Description

        When set, require the chain to be known, even if the root is self signed.

        Note that if set, and certificates are set to be verified, trusted issuers must be provided, or no connections will be accepted.

      Variable rsa

        ``__deprecated__` `Crypto.RSA.State` SSL.Context.rsa`

      Description

        Getting

        The servers default private RSA key.

        Compatibility, don't use.

      Deprecated

        Replaced by `find_cert`.

      See also

        ``certificates`, `find_cert()`

        Setting

        The servers default private RSA key.

        Compatibility, don't use.

      Deprecated

        Replaced by `find_cert`.

      See also

        ``certificates`, `find_cert()`

      Method rsa_mode

        ``__deprecated__` `void` rsa_mode(`int(0..)`|`void` `min_keylength`)`

      Description

        Set `preferred_suites` to RSA based methods.

      Parameter `min_keylength`

        Minimum acceptable key length in bits.

      See also

        `dhe_dss_mode()`, `filter_weak_suites()`

      Deprecated

        Replaced by `get_suites`.

      Variable session_lifetime

        ``int` SSL.Context.session_lifetime`

      Description

        Sessions are removed from the cache when they are older than this limit (in seconds). Sessions are also removed from the cache if a connection using the session dies unexpectedly.

      Method set_authorities

        ``void` set_authorities(`array`(`string`) `a`)`

      Description

        Array of authorities that are accepted for client certificates. The server will only accept connections from clients whose certificate is signed by one of these authorities. The string is a DER-encoded certificate, which typically must be decoded using `MIME.decode_base64` or `Standards.PEM.Messages` first.

        Note that it is presumed that the issuer will also be trusted by the server. See `trusted_issuers` for details on specifying trusted issuers.

        If empty, the server will accept any client certificate whose issuer is trusted by the server.

      Method set_trusted_issuers

        ``void` set_trusted_issuers(`array`(`array`(`string`)) `i`)`

      Description

        Sets the list of trusted certificate issuers.

      Parameter `a`

        An array of certificate chains whose root is self signed (ie a root issuer), and whose final certificate is an issuer that we trust. The root of the certificate should be first certificate in the chain. The string is a DER-encoded certificate, which typically must be decoded using `MIME.decode_base64` or `Standards.PEM.Messages` first.

        If this array is left empty, and the context is set to verify certificates, a certificate chain must have a root that is self signed.

      Variable signature_algorithms

        ``array`(`array`(`int`)) SSL.Context.signature_algorithms`

      Description

        The set of <hash, signature> combinations to use by us.

        Only used with TLS 1.2 and later.

        Defaults to all combinations supported by Pike except for MD5.

        This list is typically filtered by `get_signature_algorithms()` to get rid of combinations not supported by the runtime.

      Note

        According to RFC 5246 7.4.2 all certificates needs to be signed by any of the supported signature algorithms. To be forward compatible this list needs to be limited to the combinations that have existing PKCS identifiers.

      See also

        `get_signature_algorithms()`

      Method sort_suites

        ``array`(`int`) sort_suites(`array`(`int`) `suites`)`

      Description

        Sort a set of cipher suites according to our preferences.

      Returns

        Returns the array sorted with the most preferrable (aka "best") cipher suite first.

      Note

        The original array (`suites`) is modified destructively, but is not the same array as the result.

      Variable use_cache

        ``int` SSL.Context.use_cache`

      Description

        Non-zero to enable caching of sessions

      Variable verifier_algorithms

        ``mapping`(`Standards.ASN1.Types.Identifier`:`Crypto.Hash`) SSL.Context.verifier_algorithms`

      Description

        Mapping of supported verifier algorithms to hash implementation.

      See also

        `Standards.X509.get_algorithms()`

      Variable verify_certificates

        ``int` SSL.Context.verify_certificates`

      Description

        Determines whether certificates presented by the peer are verified, or just accepted as being valid.

    ## Class SSL.File

      Description

        Interface similar to `Stdio.File`.

        - Handles blocking and nonblocking mode.

        - Handles callback mode in an arbitrary backend (also in blocking mode).

        - Read and write operations may each do both reading and writing. In callback mode that means that installing either a read or a write callback may install both internally.

        - In Pike 8.0 and later, blocking read and write in concurrent threads is supported.

        - Callback changing operations like `set_blocking` and `set_nonblocking` aren't atomic.

        - Apart from the above, thread safety/atomicity characteristics are retained.

        - Blocking characterstics are retained for all functions.

        - `is_open`, connection init (`create`) and close (`close`) can do both reading and writing.

        - `destroy` attempts to close the stream properly by sending the close packet, but since it can't do blocking I/O it's not certain that it will succeed. The stream should therefore always be closed with an explicit `close` call.

        - Abrupt remote close without the proper handshake gets the errno `System.EPIPE`.

        - Objects do not contain cyclic references, so they are closed and destructed timely when dropped.

      Method accept

        ``bool` accept(`string`|`void` `pending_data`)`

      Description

        Configure as server and set up the connection.

      Parameter `pending_data`

        Any data that has already been read from the stream. This is typically used with protocols that use START TLS or similar, where there's a risk that "too much" data (ie part of the TLS ClientHello) has been read from the stream before deciding that the connection is to enter TLS-mode.

      Returns

        Returns `0` on handshaking failure in blocking mode, and otherwise `1`.

      See also

        `connect()`

      Variable application_protocol

        ``string` SSL.File.application_protocol`

      Description

        The application protocol chosen by the client during application layer protocol negotiation (ALPN).

      Note

        Read only

      Method backend_once

        ``protected` `int(0..0)`|`float` backend_once(`int`|`void` `nonwaiting_mode`)`

      Description

        Run one pass of the backend.

      Method close

        ``int` close(`void`|`string` `how`, `void`|`int` `clean_close`, `void`|`int` `dont_throw`)`

      Description

        Close the connection. Both the read and write ends are always closed

      Parameter `how`

        This argument is only for `Stdio.File` compatibility and must be either `"rw"` or `0`.

      Parameter `clean_close`

        If set then close messages are exchanged to shut down the SSL connection but not the underlying stream. It may then continue to be used for other communication afterwards. The default is to send a close message and then close the stream without waiting for a response.

      Parameter `dont_throw`

        I/O errors are normally thrown, but that can be turned off with `dont_throw`. In that case `errno` is set instead and `0` is returned. `1` is always returned otherwise. It's not an error to close an already closed connection.

      Note

        If a clean close is requested in nonblocking mode then the stream is most likely not closed right away, and the backend is then still needed for a while afterwards to exchange the close packets. `is_open` returns 2 in that time window.

      Note

        I/O errors from both reading and writing might occur in blocking mode.

      Note

        If a clean close is requested and data following the close message is received at the same time, then this object will read it and has no way to undo that. That data can be retrieved with `read` afterwards.

      See also

        `shutdown`

      Method connect

        ``SSL.Session` connect(`string`|`void` `dest_addr`, `SSL.Session`|`void` `session`)`

      Description

        Configure as client and set up the connection.

      Parameter `dest_addr`

        Optional name of the server that we are connected to.

      Parameter `session`

        Session to resume (if any).

      Returns

        Returns `0` on handshaking failure in blocking mode, and otherwise the `Session` object for the connection.

      Throws

        Throws an error if a connection already has been established.

      See also

        `accept()`

      Method create

        `SSL.File SSL.File(`Stdio.File` `stream`, `SSL.Context` `ctx`)`

      Description

        Create an SSL connection over an open `stream`.

      Parameter `stream`

        Open socket or pipe to create the connection over.

      Parameter `ctx`

        The SSL context.

        The backend used by `stream` is taken over and restored after the connection is closed (see `close` and `shutdown`). The callbacks and id in `stream` are overwritten.

      Note

        The operation mode defaults to nonblocking mode.

      See also

        `accept()`, `connect()`

      Method destroy

        ``protected` `void` destroy()`

      Description

        Try to close down the connection properly since it's customary to close files just by dropping them. No guarantee can be made that the close packet gets sent successfully though, because we can't risk blocking I/O here. You should call `close` explicitly.

      See also

        `close`

      Method errno

        ``int` errno()`

      Returns

        Returns the current error number for the connection. Notable values are:

        ``0`` | No error
        ``System.EPIPE`` | Connection closed by other end.

      Variable fragment_max_size

        ``protected` `int` SSL.File.fragment_max_size`

      Description

        The max amount of data to send in each packet. Initialized from the context when the object is created.

      Method get_peer_certificate_info

        ``mapping` get_peer_certificate_info()`

      Returns

        Returns peer certificate information, if any.

      Method get_peer_certificates

        ``array` get_peer_certificates()`

      Returns

        Returns the peer certificate chain, if any.

      Method internal_poll

        ``protected` `void` internal_poll()`

      Description

        Check whether any callbacks may need to be called.

        Always run via the `real_backend`.

      See also

        `schedule_poll()`

      Method is_open

        ``int` is_open()`

      Returns

        Returns nonzero if the stream currently is open, zero otherwise.

        This function does nonblocking I/O to check for a close packet in the input buffer.

        If a clean close has been requested in nonblocking mode, then 2 is returned until the close packet exchanged has been completed.

      Note

        In Pike 7.8 and earlier, this function returned zero in the case above where it now returns 2.

      Method linger

        ``bool` linger(`int(-1..65535)`|`void` `seconds`)`

      Description

        Set the linger time on `close()`.

      Method query_accept_callback

        ``function`(`void`|`object`, `void`|`mixed`:`int`) query_accept_callback()`

      Returns

        Returns the current accept callback.

      See also

        `set_accept_callback`

      Method query_address

        ``string` query_address(`int`|`void` `arg`)`

      Returns

        Returns the address and port of the connection.

        See `Stdio.File.query_address` for details.

      See also

        `Stdio.File.query_address`

      Method query_alert_callback

        ``function`(`object`, `int`|`object`, `string`:`void`) query_alert_callback()`

      Returns

        Returns the current alert callback.

      See also

        `set_alert_callback`

      Method query_application_protocol

        ``string(8bit)` query_application_protocol()`

      Returns

        Returns the negotiated application level protocol (ALPN) if any, and otherwise `0` (zero).

      See also

        `Context.advertised_protocols`

      Method query_backend

        ``Pike.Backend` query_backend()`

      Description

        Return the backend used for the file callbacks.

      See also

        `set_backend`

      Method query_buffer_mode

        ``array`(`Stdio.Buffer`|`int(0..0)`) query_buffer_mode()`

      Description

        Get the active input and output buffers that have been set with `set_buffer_mode()` (if any).

      Returns

        Returns an array with two elements:

        Array
        ``Stdio.Buffer` `0`` | The current input buffer.
        ``Stdio.Buffer` `1`` | The current output buffer.

      See also

        `set_buffer_mode()`

      Method query_callbacks

        ``array`(`function`(`mixed`, `void`|`string`:`int`)) query_callbacks()`

      Returns

        Returns the currently set callbacks in the same order as the arguments to `set_callbacks`.

      See also

        `set_callbacks`, `set_nonblocking`

      Method query_close_callback

        ``function`(`void`|`mixed`:`int`) query_close_callback()`

      Returns

        Returns the current close callback.

      See also

        `set_close_callback`, `set_nonblocking`, `query_callbacks`

      Method query_connection

        ``.Connection` query_connection()`

      Description

        Return the SSL connection object.

        This returns the low-level `SSL.connection` object.

      Method query_context

        ``SSL.Context` query_context()`

      Description

        Return the SSL context object.

      Method query_fd

        ``int` query_fd()`

      Returns

        Returns the file descriptor number associated with this object.

      Method query_id

        ``mixed` query_id()`

      Returns

        Returns the currently set id.

      See also

        `set_id`

      Method query_read_callback

        ``Stdio.read_callback_t` query_read_callback()`

      Returns

        Returns the current read callback.

      See also

        `set_read_callback`, `set_nonblocking`, `query_callbacks`

      Method query_stream

        ``Stdio.File` query_stream()`

      Description

        Return the underlying stream.

      Note

        Avoid any temptation to do `destruct(file_obj->query_stream())`. That almost certainly creates more problems than it solves.

        You probably want to use `shutdown`.

      See also

        `shutdown`

      Method query_suite

        ``int` query_suite()`

      Description

        Return the currently active cipher suite.

      Method query_timeout

        ``int(0..0)`|`float` query_timeout()`

      Description

        Get the timeout for blocking operations.

      See also

        `set_timeout()`

      Method query_version

        ``ProtocolVersion` query_version()`

      Description

        Return the currently active SSL/TLS version.

      Method query_write_callback

        ``Stdio.write_callback_t` query_write_callback()`

      Returns

        Returns the current write callback.

      See also

        `set_write_callback`, `set_nonblocking`, `query_callbacks`

      Method read

        ``string` read(`void`|`int` `length`, `void`|`bool` `not_all`)`

      Description

        Read some (decrypted) data from the connection. Works like `Stdio.File.read`.

      Note

        I/O errors from both reading and writing might occur in blocking mode.

      See also

        `write`

      Method renegotiate

        ``int` renegotiate()`

      Description

        Renegotiate the connection by starting a new handshake. Note that the accept callback will be called again when the handshake is finished.

        Returns zero if there are any I/O errors. `errno()` will give the details.

      Note

        The read buffer is not cleared - a `read()` afterwards will return data from both before and after the renegotiation.

      Bugs

        Data in the write queue in nonblocking mode is not properly written before resetting the connection. Do a blocking `write("")` first to avoid problems with that.

      Method schedule_poll

        ``protected` `void` schedule_poll()`

      Description

        Schedule calling of any relevant callbacks the next time the `real_backend` is run.

      See also

        `internal_poll()`

      Method set_accept_callback

        ``void` set_accept_callback(`function`(`void`|`object`, `void`|`mixed`:`int`) `accept`)`

      Description

        Install a function that will be called when the handshake is finished and the connection is ready for use.

        The callback function will be called with the File object and the additional id arguments (set with `set_id`).

      Note

        Like the read, write and close callbacks, installing this callback implies callback mode, even after the handshake is done.

      See also

        `set_nonblocking`, `set_callbacks`, `query_accept_callback`, `query_callbacks`

      Method set_alert_callback

        ``void` set_alert_callback(`function`(`object`, `int`|`object`, `string`:`void`) `alert`)`

      Description

        Install a function that will be called when an alert packet is about to be sent. It doesn't affect the callback mode - it's called both from backends and from within normal function calls like `read` and `write`.

        This callback can be used to implement fallback to other protocols when used on the server side together with `shutdown()`.

      Note

        This object is part of a cyclic reference whenever this is set, just like setting any other callback.

      Note

        This callback is not cleared by `set_blocking`, or settable by `set_callbacks` or `set_nonblocking`. It is also not part of the set returned by `query_callbacks`.

      See also

        `query_alert_callback`

      Method set_backend

        ``void` set_backend(`Pike.Backend` `backend`)`

      Description

        Set the backend used for the file callbacks.

      See also

        `query_backend`

      Method set_blocking

        ``void` set_blocking()`

      Description

        Set the stream in blocking mode. All but the alert callback are zapped.

      Note

        There might be some data still waiting to be written to the stream. That will be written in the next blocking call, regardless what it is.

      Note

        This function doesn't solve the case when the connection is used nonblocking in some backend thread and another thread switches it to blocking and starts using it. To solve that, put a call out in the backend from the other thread that switches it to blocking, and then wait until that call out has run.

      Note

        Prior to version 7.5.12, this function didn't clear the accept callback.

      See also

        `set_nonblocking`, `set_blocking_keep_callbacks`, `set_nonblocking_keep_callbacks`

      Method set_blocking_keep_callbacks

        ``void` set_blocking_keep_callbacks()`

      Description

        Set blocking mode like `set_blocking`, but don't alter any callbacks.

      See also

        `set_blocking`, `set_nonblocking`

      Method set_buffer_mode

        ``void` set_buffer_mode(`Stdio.Buffer`|`int(0..0)` `in`, `Stdio.Buffer`|`int(0..0)` `out`)`

      Description

        Toggle the file to Buffer mode.

        In this mode reading and writing will be done via Buffer objects, in the directions you included buffers.

      Parameter `in`

        Input buffer. If this buffer is non-empty, its contents will be returned after any already received data.

      Parameter `out`

        Output buffer. If this buffer is non-empty, its contents will be sent after any data already queued for sending.

      See also

        `query_buffer_mode()`

      Method set_callbacks

        ``void` set_callbacks(`void`|`Stdio.read_callback_t` `read`, `void`|`Stdio.write_callback_t` `write`, `void`|`function`(`mixed`:`int`) `close`, `void`|`function`(`mixed`, `string`:`int`) `read_oob`, `void`|`function`(`mixed`:`int`) `write_oob`, `void`|`function`(`void`|`mixed`:`int`) `accept`)`

      Description

        Installs all the specified callbacks at once. Use `UNDEFINED` to keep the current setting for a callback.

        Like `set_nonblocking`, the callbacks are installed atomically. As opposed to `set_nonblocking`, this function does not do anything with the stream, and it doesn't even have to be open.

      Bugs

        `read_oob` and `write_oob` are currently ignored.

      See also

        `set_read_callback`, `set_write_callback`, `set_close_callback`, `set_accept_callback`, `query_callbacks`

      Method set_close_callback

        ``void` set_close_callback(`function`(`void`|`mixed`:`int`) `close`)`

      Description

        Install a function to be called when the connection is closed, either normally or due to an error (use `errno` to retrieve it).

      See also

        `query_close_callback`, `set_nonblocking`, `query_callbacks`

      Method set_id

        ``void` set_id(`mixed` `id`)`

      Description

        Set the value to be sent as the first argument to the callbacks installed by `set_callbacks`.

      See also

        `query_id`

      Method set_nonblocking

        ``void` set_nonblocking(`void`|`Stdio.read_callback_t` `read`, `void`|`Stdio.write_callback_t` `write`, `void`|`function`(`void`|`mixed`:`int`) `close`, `void`|`function`(`void`|`mixed`:`int`) `read_oob`, `void`|`function`(`void`|`mixed`:`int`) `write_oob`, `void`|`function`(`void`|`mixed`:`int`) `accept`)`

      Description

        Set the stream in nonblocking mode, installing the specified callbacks. The alert callback isn't touched.

      Note

        Prior to version 7.5.12, this function didn't set the accept callback.

      Bugs

        `read_oob` and `write_oob` are currently ignored.

      See also

        `set_callbacks`, `query_callbacks`, `set_nonblocking_keep_callbacks`, `set_blocking`

      Method set_nonblocking_keep_callbacks

        ``void` set_nonblocking_keep_callbacks()`

      Description

        Set nonblocking mode like `set_nonblocking`, but don't alter any callbacks.

      See also

        `set_nonblocking`, `set_blocking`, `set_blocking_keep_callbacks`

      Method set_read_callback

        ``void` set_read_callback(`Stdio.read_callback_t` `read`)`

      Description

        Install a function to be called when data is available.

      See also

        `query_read_callback`, `set_nonblocking`, `query_callbacks`

      Method set_timeout

        ``void` set_timeout(`int(0..0)`|`float` `seconds`)`

      Description

        Set timeout for blocking operations.

      Parameter `seconds`

        Time in seconds allowed for blocking operations before triggering a timeout. Set to `0` (zero) to disable.

        By default there is no timeout.

      See also

        `query_timeout()`

      Method set_write_callback

        ``void` set_write_callback(`Stdio.write_callback_t` `write`)`

      Description

        Install a function to be called when data can be written.

      See also

        `query_write_callback`, `set_nonblocking`, `query_callbacks`

      Method shutdown

        ``Stdio.File` shutdown()`

      Description

        Shut down the SSL connection without sending any more packets.

        If the connection is open then the underlying (still open) stream is returned.

        If a nonclean (i.e. normal) close has been requested then the underlying stream is closed now if it wasn't closed already, and zero is returned.

        If a clean close has been requested (see the second argument to `close`) then the behavior depends on the state of the close packet exchange: The first `shutdown` call after a successful exchange returns the (still open) underlying stream, and later calls return zero and clears `errno`. If the exchange hasn't finished then the stream is closed, zero is returned, and `errno` will return `System.EPIPE`.

      See also

        `close`, `set_alert_callback`

      Method write

        ``int` write(`string`|`array`(`string`) `data`, `mixed` ... `args`)`

      Description

        Write some (unencrypted) data to the connection. Works like `Stdio.File.write` except that this function often buffers some data internally, so there's no guarantee that all the consumed data has been successfully written to the stream in nonblocking mode. It keeps the internal buffering to a minimum, however.

      Note

        This function returns zero if attempts are made to write data during the handshake phase and the mode is nonblocking.

      Note

        I/O errors from both reading and writing might occur in blocking mode.

      See also

        `read`

    ## Class SSL.Packet

      Description

        SSL Record Layer. Handle formatting and parsing of packets.

      Method create

        `SSL.Packet SSL.Packet(`ProtocolVersion` `version`, `void`|`int` `extra`)`

      Parameter `version`

        The version sent packets will be created for.

      Parameter `extra`

        Additional fragment size, over the 2^14 bytes for a plaintext TLS fragment.

      Method recv

        ``string(8bit)`|`.Packet` recv(`string(8bit)` `data`)`

      Description

        Receive data read from the network.

      Parameter `data`

        Raw data from the network.

      Returns

        Returns a string of leftover data if packet is complete, otherwise `0`.

        If there's an error, an alert object is returned.

      Method send

        ``string` send()`

      Description

        Serialize the packet for sending.

      Returns

        Returns the serialized packet.

    ## Class SSL.Port

      Description

        Interface similar to `Stdio.Port`.

      Method accept

        ``File` accept()`

      Description

        Get the next pending `File` from the `accept_queue`.

      Returns

        Returns the next pending `File` if any, and `0` (zero) if there are none.

      Variable accept_callback

        ``function`(`object`, `mixed`|`void`:`void`) SSL.Port.accept_callback`

      Method bind

        ``int` bind(`int` `port`, `function`(`SSL.File`|`void`, `mixed`|`void`:`int`) `callback`, `string`|`void` `ip`, `int`|`void` `share`)`

      Description

        Bind an SSL port.

      Parameter `port`

        Port number to bind.

      Parameter `callback`

        Callback to call when the SSL connection has been negotiated.

        The callback is called with an `File` as the first argument, and the id for the `File` as the second.

        If the `callback` is `0` (zero), then negotiated `File`s will be enqueued for later retrieval with `accept()`.

      Parameter `ip`

        Optional IP-number to bind.

      Parameter `share`

        If true, share the port with other processes

      Returns

        Returns `1` if binding of the port succeeded, and `0` (zero) on failure.

      See also

        `Stdio.Port()->bind()`, `File()->set_accept_callback()`, `listen_fd()`

      Method create

        `SSL.Port SSL.Port(`Context`|`void` `ctx`)`

      Description

        Create a new port for accepting SSL connections.

      See also

        `bind()`, `listen_fd()`

      Variable ctx

        ``Context` SSL.Port.ctx`

      Description

        Context to use for the connections.

      Method finished_callback

        ``void` finished_callback(`SSL.File` `f`, `mixed`|`void` `id`)`

      Description

        SSL connection accept callback.

      Parameter `f`

        The `File` that just finished negotiation.

        This function is installed as the `File` accept callback by `ssl_callback()`, and enqueues the newly negotiated `File` on the accept queue.

        If there has been an `accept_callback` installed by `bind()` or `listen_fd()`, it will be called with all pending `File`s on the accept queue.

        If there's no `accept_callback`, then the `File` will have to be retrieved from the queue by calling `accept()`.

      Inherit socket

        `inherit Stdio.Port : socket`

      Method listen_fd

        ``int` listen_fd(`int` `fd`, `function`(`File`|`void`, `mixed`|`void`:`int`) `callback`)`

      Description

        Set up listening for SSL connections on an already opened fd.

      Parameter `fd`

        File descriptor to listen on.

      Parameter `callback`

        Callback to call when the SSL connection has been negotiated.

        The callback is called with an `File` as the first argument, and the id for the `File` as the second.

        If the `callback` is `0` (zero), then negotiated `File`s will be enqueued for later retrieval with `accept()`.

      Returns

        Returns `1` if listening on the fd succeeded, and `0` (zero) on failure.

      See also

        `Stdio.Port()->listen_fd()`, `File()->set_accept_callback()`, `bind()`

      Method socket_accept

        ``Stdio.File` socket_accept()`

      Description

        Low-level accept.

      See also

        `Stdio.Port()->accept()`

      Method ssl_callback

        ``void` ssl_callback(`mixed` `id`)`

      Description

        Connection accept callback.

        This function is installed as the `Stdio.Port` callback, and accepts the connection and creates a corresponding `File` with `finished_callback()` as the accept callback.

      See also

        `bind()`, `finished_callback()`

    ## Class SSL.ServerConnection

      Description

        Server-side connection state.

      Method handle_handshake

        ``int(-1..1)` handle_handshake(`int` `type`, `string(8bit)` `data`, `string(8bit)` `raw`)`

      Description

        Do handshake processing. Type is one of HANDSHAKE_*, data is the contents of the packet, and raw is the raw packet received (needed for supporting SSLv2 hello messages).

        This function returns 0 if handshake is in progress, 1 if handshake is finished, and -1 if a fatal error occurred. It uses the send_packet() function to transmit packets.

      Inherit Connection

        `inherit Connection : Connection`

      Method send_renegotiate

        ``void` send_renegotiate()`

      Description

        Renegotiate the connection (server initiated).

        Sends a `hello_request` to force a new round of handshaking.

    ## Class SSL.Session

      Description

        The most important information in a session object is a choice of encryption algorithms and a "master secret" created by keyexchange with a client. Each connection can either do a full key exchange to established a new session, or reuse a previously established session. That is why we have the session abstraction and the session cache. Each session is used by one or more connections, in sequence or simultaneously.

        It is also possible to change to a new session in the middle of a connection.

      Variable cert_data

        ``mapping` SSL.Session.cert_data`

      Description

        Information about the certificate in use by the peer, such as issuing authority, and verification status.

      Variable certificate_chain

        ``array`(`string(8bit)`) SSL.Session.certificate_chain`

      Description

        our certificate chain

      Variable cipher_spec

        ``Cipher.CipherSpec` SSL.Session.cipher_spec`

      Description

        Information about the encryption method derived from the cipher_suite.

      Variable cipher_suite

        ``int` SSL.Session.cipher_suite`

      Description

        Constant defining a choice of keyexchange, encryption and mac algorithm.

      Variable compression_algorithm

        ``int` SSL.Session.compression_algorithm`

      Description

        Always COMPRESSION_null.

      Variable curve

        ``Crypto.ECC.Curve` SSL.Session.curve`

      Description

        The ECC curve selected by the key exchange.

        ``KE_ecdh_ecdsa`` | The curve from the server certificate.
        ``KE_ecdh_rsa``
        ``KE_ecdhe_ecdsa`` | The curve selected for the ECDHE key exchange (typically the largest curve supported by both the client and the server).
        ``KE_ecdhe_rsa``
        ``KE_ecdh_anon``

      Variable ecc_curves

        ``array`(`int`) SSL.Session.ecc_curves`

      Description

        Supported elliptical curve cipher curves in order of preference.

      Variable ecc_point_format

        ``int` SSL.Session.ecc_point_format`

      Description

        The selected elliptical curve point format.

      Note

        May be `-1` to indicate that there's no supported overlap between the server and client.

      Variable encrypt_then_mac

        ``int` SSL.Session.encrypt_then_mac`

      Description

        Negotiated encrypt-then-mac mode.

      Method generate_keys

        ``array`(`string(8bit)`) generate_keys(`string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

      Description

        Generates keys appropriate for the SSL version given in `version`, based on the `client_random` and `server_random`.

      Returns

        Array
        ``string` `0`` | Client write MAC secret
        ``string` `1`` | Server write MAC secret
        ``string` `2`` | Client write key
        ``string` `3`` | Server write key
        ``string` `4`` | Client write IV
        ``string` `5`` | Server write IV

      Method has_required_certificates

        ``bool` has_required_certificates()`

      Description

        Indicates if this session has the required server certificate keys set. No means that no or the wrong type of certificate was sent from the server.

      Variable heartbeat_mode

        ``HeartBeatModeType` SSL.Session.heartbeat_mode`

      Description

        Heartbeat mode.

      Variable identity

        ``string(8bit)` SSL.Session.identity`

      Description

        Identifies the session to the server

      Method is_supported_cert

        ``protected` `bool` is_supported_cert(`CertificatePair` `cp`, `int` `ke_mask`, `int` `h_max`, `ProtocolVersion` `version`, `array`(`int`) `ecc_curves`)`

      Description

        Used to filter certificates not supported by the peer.

      Parameter `cp`

        Candidate `CertificatePair`.

      Parameter `version`

        Negotiated version of SSL.

      Parameter `ecc_curves`

        The set of ecc_curves supported by the peer.

      Method is_supported_suite

        ``bool` is_supported_suite(`int` `suite`, `int` `ke_mask`, `ProtocolVersion` `version`)`

      Description

        Used to filter the set of cipher suites suggested by the peer based on our available certificates.

      Parameter `suite`

        Candidate cipher suite.

      Parameter `ke_mask`

        The bit mask of the key exchange algorithms supported by the set of available certificates.

      Parameter `version`

        The negotiated version of SSL/TLS.

      Variable master_secret

        ``string(8bit)` SSL.Session.master_secret`

      Description

        48 byte secret shared between the client and the server. Used for deriving the actual keys.

      Variable max_packet_size

        ``int` SSL.Session.max_packet_size`

      Description

        The max fragment size requested by the client.

      Method new_client_states

        ``array`(`State`) new_client_states(`.Connection` `con`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

      Description

        Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.

      Returns

        Array
        ``SSL.State` `read_state`` | Read state
        ``SSL.State` `write_state`` | Write state

      Method new_server_states

        ``array`(`State`) new_server_states(`.Connection` `con`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

      Description

        Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.

      Returns

        Array
        ``SSL.State` `read_state`` | Read state
        ``SSL.State` `write_state`` | Write state

      Variable peer_certificate_chain

        ``array`(`string(8bit)`) SSL.Session.peer_certificate_chain`

      Description

        the peer certificate chain

      Variable peer_public_key

        ``Crypto.Sign.State` SSL.Session.peer_public_key`

      Description

        The peer's public key (from the certificate).

      Variable private_key

        ``Crypto.Sign.State` SSL.Session.private_key`

      Description

        Our private key.

      Method reusable_as

        ``bool` reusable_as(`Session` `other`)`

      Description

        Returns true if this session object can be used in place of the session object `other`.

      Method select_cipher_suite

        ``int` select_cipher_suite(`array`(`CertificatePair`) `certs`, `array`(`int`) `cipher_suites`, `ProtocolVersion` `version`)`

      Description

        Selects an apropriate certificate, authentication method and cipher suite for the parameters provided by the client.

      Parameter `certs`

        The list of `CertificatePair`s that are applicable to the `server_name` of this session.

      Parameter `client_suites`

        The set of cipher suites that the client claims to support.

      Parameter `version`

        The SSL protocol version to use.

        Typical client extensions that also are used:

        `signature_algorithms`

          The set of signature algorithm tuples that the client claims to support.

      Variable server_name

        ``string(8bit)` SSL.Session.server_name`

      Description

        RFC 6066 3.1 (SNI)

      Method set_cipher_suite

        ``int` set_cipher_suite(`int` `suite`, `ProtocolVersion` `version`, `array`(`array`(`int`)) `signature_algorithms`, `int` `max_hash_size`)`

      Description

        Sets the proper authentication method and cipher specification for the given parameters.

      Parameter `suite`

        The cipher suite to use, selected from the set that the client claims to support.

      Parameter `version`

        The SSL protocol version to use.

      Parameter `signature_algorithms`

        The set of signature algorithms tuples that the client claims to support.

      Parameter `max_hash_size`

      Method set_compression_method

        ``void` set_compression_method(`int` `compr`)`

      Description

        Sets the compression method. Currently only `COMPRESSION_null` and `COMPRESSION_deflate` are supported.

      Variable signature_algorithms

        ``array`(`array`(`int`)) SSL.Session.signature_algorithms`

      Description

        The set of <hash, signature> combinations supported by the peer.

        Only used with TLS 1.2 and later.

        Defaults to the settings from RFC 5246 7.4.1.4.1.

      Variable ticket

        ``string(8bit)` SSL.Session.ticket`

      Description

        Alternative identification of the session to the server.

      See also

        RFC 4507, RFC 5077

      Variable ticket_expiry_time

        ``int` SSL.Session.ticket_expiry_time`

      Description

        Expiry time for `ticket`.

      Variable truncated_hmac

        ``bool` SSL.Session.truncated_hmac`

      Description

        Indicates that the packet HMACs should be truncated to the first 10 bytes (80 bits). Cf RFC 3546 3.5.

      Variable version

        ``ProtocolVersion` SSL.Session.version`

      Description

        Negotiated protocol version.

    ## Class SSL.State

      Description

        The state object handles a one-way stream of packets, and operates in either decryption or encryption mode. A connection switches from one set of state objects to another, one or more times during its lifetime.

      Variable crypt

        ``Cipher.CipherAlgorithm` SSL.State.crypt`

      Description

        Encryption or decryption object.

      Method decrypt_packet

        ``Alert`|`Packet` decrypt_packet(`Packet` `packet`)`

      Description

        Destructively decrypts a packet (including inflating and MAC-verification, if needed). On success, returns the decrypted packet. On failure, returns an alert packet. These cases are distinguished by looking at the is_alert attribute of the returned packet.

      Method encrypt_packet

        ``Alert`|`Packet` encrypt_packet(`Packet` `packet`)`

      Description

        Encrypts a packet (including deflating and MAC-generation).

      Variable mac

        ``Cipher.MACAlgorithm` SSL.State.mac`

      Description

        Message Authentication Code

      Variable salt

        ``string` SSL.State.salt`

      Description

        TLS 1.2 IV salt. This is used as a prefix for the IV for the AEAD cipher algorithms.

      Variable seq_num

        ``int` SSL.State.seq_num`

      Description

        64-bit sequence number.

      Variable session

        ``Session` SSL.State.session`

      Description

        Information about the used algorithms.

      Variable tls_iv

        ``int` SSL.State.tls_iv`

      Description

        TLS IV prefix length.

    ## Class SSL.https

      Description

        Dummy HTTPS server/client

    ## Module SSL.Cipher

      Description

        Encryption and MAC algorithms used in SSL.

      Method P_hash

        ``protected` `string(8bit)` P_hash(`Crypto.Hash` `hashfn`, `string(8bit)` `secret`, `string(8bit)` `seed`, `int` `len`)`

      Description

        Hashfn is either a `Crypto.MD5`, `Crypto.SHA` or `Crypto.SHA256`.

      Method lookup

        ``CipherSpec` lookup(`int` `suite`, `ProtocolVersion`|`int` `version`, `array`(`array`(`int`)) `signature_algorithms`, `int` `max_hash_size`)`

      Description

        Lookup the crypto parameters for a cipher suite.

      Parameter `suite`

        Cipher suite to lookup.

      Parameter `version`

        Version of the SSL/TLS protocol to support.

      Parameter `signature_algorithms`

        The set of <hash, signature> combinations that are supported by the other end.

      Parameter `max_hash_size`

        The maximum hash size supported for the signature algorithm.

      Returns

        Returns `0` (zero) for unsupported combinations, otherwise returns an initialized `CipherSpec` for the `suite`.

      Method prf_sha384

        ``string(8bit)` prf_sha384(`string(8bit)` `secret`, `string(8bit)` `label`, `string(8bit)` `seed`, `int` `len`)`

      Description

        This Pseudo Random Function is used to derive secret keys for some ciphers suites defined after TLS 1.2.

      Method prf_sha512

        ``string(8bit)` prf_sha512(`string(8bit)` `secret`, `string(8bit)` `label`, `string(8bit)` `seed`, `int` `len`)`

      Description

        This Pseudo Random Function could be used to derive secret keys for some ciphers suites defined after TLS 1.2.

      Method prf_ssl_3_0

        ``string(8bit)` prf_ssl_3_0(`string(8bit)` `secret`, `string(8bit)` `label`, `string(8bit)` `seed`, `int` `len`)`

      Description

        This Pseudo Random Function is used to derive secret keys in SSL 3.0.

      Note

        The argument `label` is ignored.

      Method prf_tls_1_0

        ``string(8bit)` prf_tls_1_0(`string(8bit)` `secret`, `string(8bit)` `label`, `string(8bit)` `seed`, `int` `len`)`

      Description

        This Pseudo Random Function is used to derive secret keys in TLS 1.0 and 1.1.

      Method prf_tls_1_2

        ``string(8bit)` prf_tls_1_2(`string(8bit)` `secret`, `string(8bit)` `label`, `string(8bit)` `seed`, `int` `len`)`

      Description

        This Pseudo Random Function is used to derive secret keys in TLS 1.2.

      ## Class SSL.Cipher.CipherAlgorithm

        Description

          Cipher algorithm interface.

        Method block_size

          ``int(0..)` block_size()`

        Description

          Return the block size for this crypto.

        Method set_encrypt_key
        Method set_decrypt_key

          ``this_program` set_encrypt_key(`string`)`
          ``this_program` set_decrypt_key(`string`)`

        Description

          Set the key used for encryption/decryption, and enter encryption mode.

      ## Class SSL.Cipher.CipherSpec

        Description

          Cipher specification.

        Variable bulk_cipher_algorithm

          ``program` SSL.Cipher.CipherSpec.bulk_cipher_algorithm`

        Description

          The algorithm to use for the bulk of the transfered data.

        Variable explicit_iv_size

          ``int` SSL.Cipher.CipherSpec.explicit_iv_size`

        Description

          The number of bytes of explicit data needed for initialization vectors. This is used by AEAD ciphers, where there's a secret part of the iv "salt" of length `iv_size`, and an explicit part that is sent in the clear.

          This is usually `bulk_cipher_algorithm->iv_size() - iv_size`, but may be set to zero to just have the sequence number expanded to the same size as an implicit iv. This is used by the suites with `Crypto.ChaCha20.POLY1305`.

        Variable hash

          ``Crypto.Hash` SSL.Cipher.CipherSpec.hash`

        Description

          The hash algorithm for signing the handshake.

          Usually the same hash as is the base for the `prf`.

        Note

          Only used in TLS 1.2 and later.

        Variable hash_size

          ``int` SSL.Cipher.CipherSpec.hash_size`

        Description

          The number of bytes in the MAC hashes.

        Variable is_exportable

          ``int` SSL.Cipher.CipherSpec.is_exportable`

        Description

          Indication whether the combination uses strong or weak (aka exportable) crypto.

        Variable iv_size

          ``int` SSL.Cipher.CipherSpec.iv_size`

        Description

          The number of bytes of random data needed for initialization vectors.

        Variable ke_factory

          ``program` SSL.Cipher.CipherSpec.ke_factory`

        Description

          Key exchange factory.

        Variable key_bits

          ``int` SSL.Cipher.CipherSpec.key_bits`

        Description

          The effective number of bits in `key_material`.

          This is typically `key_material * 8`, but for eg `DES` this is `key_material * 7`.

        Variable key_material

          ``int` SSL.Cipher.CipherSpec.key_material`

        Description

          The number of bytes of key material used on initialization.

        Variable mac_algorithm

          ``program` SSL.Cipher.CipherSpec.mac_algorithm`

        Description

          The Message Authentication Code to use for the packets.

        Variable prf

          ``function`(`string(8bit)`, `string(8bit)`, `string(8bit)`, `int`:`string(8bit)`) SSL.Cipher.CipherSpec.prf`

        Description

          The Pseudo Random Function to use.

        See also

          `prf_ssl_3_0()`, `prf_tls_1_0()`, `prf_tls_1_2()`

        Method sign

          ``ADT.struct` sign(`object` `session`, `string(8bit)` `cookie`, `ADT.struct` `struct`)`

        Description

          The function used to sign packets.

        Variable signature_alg

          ``SignatureAlgorithm` SSL.Cipher.CipherSpec.signature_alg`

        Description

          The signature algorithm used for key exchange signatures.

        Variable signature_hash

          ``HashAlgorithm` SSL.Cipher.CipherSpec.signature_hash`

        Description

          The hash algorithm used for key exchange signatures.

        Method verify

          ``bool` verify(`object` `session`, `string` `cookie`, `ADT.struct` `struct`, `ADT.struct` `input`)`

        Description

          The function used to verify the signature for packets.

      ## Class SSL.Cipher.DES

        Inherit State

          `inherit Crypto.DES.CBC.Buffer.State : State`

      ## Class SSL.Cipher.DES3

        Inherit State

          `inherit Crypto.DES3.CBC.Buffer.State : State`

      ## Class SSL.Cipher.DHKeyExchange

        Description

          Implements Diffie-Hellman key-exchange.

          The following key exchange methods are implemented here: `KE_dhe_dss`, `KE_dhe_rsa` and `KE_dh_anon`.

        Method create

          `SSL.Cipher.DHKeyExchange SSL.Cipher.DHKeyExchange(`Crypto.DH.Parameters` `p`)`

        Variable parameters

          ``Crypto.DH.Parameters` SSL.Cipher.DHKeyExchange.parameters`

        Description

          Finite field Diffie-Hellman parameters.

        Method set_other

          ``this_program` set_other(`Gmp.mpz` `o`)`

        Description

          Set the value received from the peer.

        Returns

          Returns `UNDEFINED` if `o` is invalid for the set `parameters`.

          Otherwise returns the current object.

      ## Class SSL.Cipher.KeyExchange

        Description

          KeyExchange method base class.

        Variable anonymous

          ``int` SSL.Cipher.KeyExchange.anonymous`

        Description

          Indicates whether a certificate isn't required.

        Method client_key_exchange_packet

          ``string` client_key_exchange_packet(`string` `client_random`, `string` `server_random`, `ProtocolVersion` `version`)`

        Returns

          Returns the payload for a `HANDSHAKE_client_key_exchange` packet. May return `0` (zero) to generate an `ALERT_unexpected_message`.

        Variable context
        Variable session
        Variable connection
        Variable client_version

          ``object` SSL.Cipher.KeyExchange.context`
          ``object` SSL.Cipher.KeyExchange.session`
          ``object` SSL.Cipher.KeyExchange.connection`
          ``ProtocolVersion` SSL.Cipher.KeyExchange.client_version`

        Method create

          `SSL.Cipher.KeyExchange SSL.Cipher.KeyExchange(`object` `context`, `object` `session`, `object` `connection`, `ProtocolVersion` `client_version`)`

        Method derive_master_secret

          ``string` derive_master_secret(`string` `premaster_secret`, `string` `client_random`, `string` `server_random`, `ProtocolVersion` `version`)`

        Description

          Derive the master secret from the premaster_secret and the random seeds.

        Returns

          Returns the master secret.

        Variable message_was_bad

          ``int` SSL.Cipher.KeyExchange.message_was_bad`

        Description

          Indicates whether the key exchange has failed due to bad MACs.

        Method parse_server_key_exchange

          ``ADT.struct` parse_server_key_exchange(`ADT.struct` `input`)`

        Parameter `input`

          `ADT.struct` with the content of a `HANDSHAKE_server_key_exchange`.

        Returns

          The key exchange information should be extracted from `input`, so that it is positioned at the signature.

          Returns a new `ADT.struct` with the unsigned payload of `input`.

        Method server_derive_master_secret

          ``string(8bit)`|`int(8bit)` server_derive_master_secret(`string(8bit)` `data`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

        Parameter `data`

          Payload from a `HANDSHAKE_client_key_exchange`.

        Returns

          Master secret or alert number.

        Note

          May set `message_was_bad` and return a fake master secret.

        Method server_key_exchange

          ``int` server_key_exchange(`ADT.struct` `input`, `string` `client_random`, `string` `server_random`)`

        Parameter `input`

          `ADT.struct` with the content of a `HANDSHAKE_server_key_exchange`.

          The default implementation calls `parse_server_key_exchange()`, and then verifies the signature.

        Returns

          ``0`` | Returns zero on success.
          ``-1`` | Returns negative on verification failure.

        Method server_key_exchange_packet

          ``string` server_key_exchange_packet(`string` `client_random`, `string` `server_random`)`

        Description

          The default implementation calls `server_key_params()` to generate the base payload.

        Returns

          Returns the signed payload for a `HANDSHAKE_server_key_exchange`.

        Method server_key_params

          ``ADT.struct` server_key_params()`

        Returns

          Returns an `ADT.struct` with the `HANDSHAKE_server_key_exchange` payload.

      ## Class SSL.Cipher.KeyExchangeDH

        Description

          Key exchange for `KE_dh_dss` and `KE_dh_dss`.

          `KeyExchange` that uses Diffie-Hellman with a key from a DSS certificate.

        Inherit KeyExchange

          `inherit KeyExchange : KeyExchange`

        Method server_derive_master_secret

          ``string(8bit)`|`int(8bit)` server_derive_master_secret(`string(8bit)` `data`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

        Returns

          Master secret or alert number.

      ## Class SSL.Cipher.KeyExchangeDHE

        Description

          KeyExchange for `KE_dhe_rsa`, `KE_dhe_dss` and `KE_dh_anon`.

          KeyExchange that uses Diffie-Hellman to generate an Ephemeral key.

        Inherit KeyExchangeDH

          `inherit KeyExchangeDH : KeyExchangeDH`

        Method server_derive_master_secret

          ``string(8bit)`|`int(8bit)` server_derive_master_secret(`string(8bit)` `data`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

        Returns

          Master secret or alert number.

      ## Class SSL.Cipher.KeyExchangeECDH

        Description

          KeyExchange for `KE_ecdh_rsa` and `KE_ecdh_ecdsa`.

          NB: The only difference between the two is whether the certificate is signed with RSA or ECDSA.

          This KeyExchange uses the Elliptic Curve parameters from the ECDSA certificate on the server side, and ephemeral parameters on the client side.

        Inherit KeyExchange

          `inherit KeyExchange : KeyExchange`

        Method server_derive_master_secret

          ``string(8bit)`|`int(8bit)` server_derive_master_secret(`string(8bit)` `data`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

        Returns

          Master secret or alert number.

      ## Class SSL.Cipher.KeyExchangeECDHE

        Description

          KeyExchange for `KE_ecdhe_rsa` and `KE_ecdhe_ecdsa`.

          KeyExchange that uses Elliptic Curve Diffie-Hellman to generate an Ephemeral key.

        Inherit KeyExchangeECDH

          `inherit KeyExchangeECDH : KeyExchangeECDH`

        Method server_derive_master_secret

          ``string(8bit)`|`int(8bit)` server_derive_master_secret(`string(8bit)` `data`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

        Returns

          Master secret or alert number.

      ## Class SSL.Cipher.KeyExchangeNULL

        Description

          Key exchange for `KE_null`.

          This is the NULL `KeyExchange`, which is only used for the `SSL_null_with_null_null` cipher suite, which is usually disabled.

        Inherit KeyExchange

          `inherit KeyExchange : KeyExchange`

        Method server_derive_master_secret

          ``string(8bit)` server_derive_master_secret(`string(8bit)` `data`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

        Returns

          Master secret or alert number.

      ## Class SSL.Cipher.KeyExchangeRSA

        Description

          Key exchange for `KE_rsa`.

          `KeyExchange` that uses the Rivest Shamir Adelman algorithm.

        Inherit KeyExchange

          `inherit KeyExchange : KeyExchange`

        Method server_derive_master_secret

          ``string(8bit)`|`int(8bit)` server_derive_master_secret(`string(8bit)` `data`, `string(8bit)` `client_random`, `string(8bit)` `server_random`, `ProtocolVersion` `version`)`

        Returns

          Master secret or alert number.

      ## Class SSL.Cipher.MACAlgorithm

        Description

          Message Authentication Code interface.

        Method block_size

          ``int` block_size()`

        Description

          The block size of the underlying hash algorithm.

        Method hash

          ``string` hash(`string` `data`)`

        Description

          Creates a HMAC hash of the `data` with the underlying hash algorithm.

        Constant hash_header_size

          ``constant` `int` SSL.Cipher.MACAlgorithm.`hash_header_size``

        Description

          The length of the header prefixed by `hash()`.

        Method hash_packet

          ``string` hash_packet(`object` `packet`, `int` `seq_num`, `int`|`void` `adjust_len`)`

        Description

          Generates a header and creates a HMAC hash for the given `packet`.

        Parameter `packet`

          `Packet` to generate a MAC hash for.

        Parameter `seq_num`

          Sequence number for the packet in the stream.

        Parameter `adjust_len`

          Added to `sizeof(packet)` to get the packet length.

        Returns

          Returns the MAC hash for the `packet`.

        Method hash_raw

          ``string` hash_raw(`string` `data`)`

        Description

          Creates a normal hash of the `data` using the underlying hash algorithm.

      ## Class SSL.Cipher.MAChmac_md5

        Description

          HMAC using MD5.

          This is the MAC algorithm used by TLS 1.0 and later.

        Inherit MAChmac_sha

          `inherit MAChmac_sha : MAChmac_sha`

      ## Class SSL.Cipher.MAChmac_sha

        Description

          HMAC using SHA.

          This is the MAC algorithm used by TLS 1.0 and later.

        Method create

          `SSL.Cipher.MAChmac_sha SSL.Cipher.MAChmac_sha(`string`|`void` `s`)`

        Inherit MACAlgorithm

          `inherit MACAlgorithm : MACAlgorithm`

      ## Class SSL.Cipher.MAChmac_sha256

        Description

          HMAC using SHA256.

          This is the MAC algorithm used by some cipher suites in TLS 1.2 and later.

        Inherit MAChmac_sha

          `inherit MAChmac_sha : MAChmac_sha`

      ## Class SSL.Cipher.MAChmac_sha384

        Description

          HMAC using SHA384.

          This is a MAC algorithm used by some cipher suites in TLS 1.2 and later.

        Inherit MAChmac_sha

          `inherit MAChmac_sha : MAChmac_sha`

      ## Class SSL.Cipher.MAChmac_sha512

        Description

          HMAC using SHA512.

          This is a MAC algorithm used by some cipher suites in TLS 1.2 and later.

        Inherit MAChmac_sha

          `inherit MAChmac_sha : MAChmac_sha`

      ## Class SSL.Cipher.MACmd5

        Description

          MAC using MD5.

        Note

          Note: This uses the algorithm from the SSL 3.0 draft.

        Inherit MACsha

          `inherit MACsha : MACsha`

      ## Class SSL.Cipher.MACsha

        Description

          MAC using SHA.

        Note

          Note: This uses the algorithm from the SSL 3.0 draft.

        Inherit MACAlgorithm

          `inherit MACAlgorithm : MACAlgorithm`

      ## Class SSL.Cipher.RC2

        Inherit State

          `inherit Crypto.Arctwo.CBC.Buffer.State : State`

    ## Module SSL.Constants

      Description

        Protocol constants

      Constant CIPHER_effective_keylengths

        ``constant` SSL.Constants.`CIPHER_effective_keylengths``

      Description

        Mapping from cipher algorithm to effective key length.

      Constant ECC_NAME_TO_CURVE

        ``constant` SSL.Constants.`ECC_NAME_TO_CURVE``

      Description

        Lookup for Pike ECC name to `NamedCurve`.

      Constant HASH_lookup

        ``constant` SSL.Constants.`HASH_lookup``

      Description

        Lookup from `HashAlgorithm` to corresponding `Crypto.Hash`.

      Constant KE_Anonymous

        ``constant` SSL.Constants.`KE_Anonymous``

      Description

        Lists `KeyExchangeType` that doesn't require certificates.

      Constant PROTOCOL_SSL_MAX
      Constant PROTOCOL_TLS_MAX

        ``constant` SSL.Constants.`PROTOCOL_SSL_MAX``
        ``constant` SSL.Constants.`PROTOCOL_TLS_MAX``

      Description

        Max supported SSL version.

      ## Enum SSL.Constants.CertificateType

        Description

          Certificate format types as per RFC 6091 and RFC 7250.

      ## Enum SSL.Constants.CipherModes

        Description

          Cipher operation modes.

        Constant MODE_cbc

          ``constant` SSL.Constants.`MODE_cbc``

        Description

          CBC - Cipher Block Chaining mode.

        Constant MODE_ccm

          ``constant` SSL.Constants.`MODE_ccm``

        Description

          CCM - Counter with CBC-MAC mode.

        Constant MODE_ccm_8

          ``constant` SSL.Constants.`MODE_ccm_8``

        Description

          CCM - Counter with 8 bit CBC-MAC mode.

        Constant MODE_gcm

          ``constant` SSL.Constants.`MODE_gcm``

        Description

          GCM - Galois Cipher Mode.

        Constant MODE_poly1305

          ``constant` SSL.Constants.`MODE_poly1305``

        Description

          Poly1305 - Used only with ChaCha20.

      ## Enum SSL.Constants.CompressionType

        Description

          Compression methods.

        Constant COMPRESSION_deflate

          ``constant` SSL.Constants.`COMPRESSION_deflate``

        Description

          Deflate compression. RFC 3749

        Constant COMPRESSION_lzs

          ``constant` SSL.Constants.`COMPRESSION_lzs``

        Description

          LZS compression. RFC 3943

        Constant COMPRESSION_null

          ``constant` SSL.Constants.`COMPRESSION_null``

        Description

          No compression.

      ## Enum SSL.Constants.ConnectionState

        Description

          Connection states.

          These are the states that a [Connection] may have.

          Queueing of more application data is only allowed in the states `CONNECTION_ready` and `CONNECTION_handshaking`.

        Constant CONNECTION_closed

          ``constant` SSL.Constants.`CONNECTION_closed``

        Description

          Closed at both ends.

        Constant CONNECTION_closing

          ``constant` SSL.Constants.`CONNECTION_closing``

        Description

          Connection closing mask.

        Constant CONNECTION_failing

          ``constant` SSL.Constants.`CONNECTION_failing``

        Description

          Connection failing mask.

        Constant CONNECTION_handshaking

          ``constant` SSL.Constants.`CONNECTION_handshaking``

        Description

          Handshaking not done.

        Constant CONNECTION_local_closed

          ``constant` SSL.Constants.`CONNECTION_local_closed``

        Description

          Local close packet sent.

        Constant CONNECTION_local_closing

          ``constant` SSL.Constants.`CONNECTION_local_closing``

        Description

          Local close packet pending.

        Constant CONNECTION_local_down

          ``constant` SSL.Constants.`CONNECTION_local_down``

        Description

          Local mask.

        Constant CONNECTION_local_failing

          ``constant` SSL.Constants.`CONNECTION_local_failing``

        Description

          Fatal alert pending.

        Constant CONNECTION_local_fatal

          ``constant` SSL.Constants.`CONNECTION_local_fatal``

        Description

          Fatal alert sent.

        Constant CONNECTION_peer_closed

          ``constant` SSL.Constants.`CONNECTION_peer_closed``

        Description

          Peer has closed the connection.

        Constant CONNECTION_peer_down

          ``constant` SSL.Constants.`CONNECTION_peer_down``

        Description

          Peer mask.

        Constant CONNECTION_peer_fatal

          ``constant` SSL.Constants.`CONNECTION_peer_fatal``

        Description

          Peer has issued a fatal alert.

        Constant CONNECTION_ready

          ``constant` SSL.Constants.`CONNECTION_ready``

        Description

          Connection is ready for use.

      ## Enum SSL.Constants.FragmentLength

        Description

          Fragment lengths for `EXTENSION_max_fragment_length`.

      ## Enum SSL.Constants.HashAlgorithm

        Description

          Hash algorithms as per RFC 5246 7.4.1.4.1.

      ## Enum SSL.Constants.KeyExchangeType

        Description

          Key exchange methods.

        Constant KE_dh_anon

          ``constant` SSL.Constants.`KE_dh_anon``

        Description

          Diffie-Hellman Anonymous

        Constant KE_dh_dss

          ``constant` SSL.Constants.`KE_dh_dss``

        Description

          Diffie-Hellman cert signed with DSS

        Constant KE_dh_rsa

          ``constant` SSL.Constants.`KE_dh_rsa``

        Description

          Diffie-Hellman cert signed with RSA

        Constant KE_dhe_dss

          ``constant` SSL.Constants.`KE_dhe_dss``

        Description

          Diffie-Hellman Ephemeral DSS

        Constant KE_dhe_psk

          ``constant` SSL.Constants.`KE_dhe_psk``

        Description

          Preshared Key with DHE

        Constant KE_dhe_rsa

          ``constant` SSL.Constants.`KE_dhe_rsa``

        Description

          Diffie-Hellman Ephemeral RSA

        Constant KE_ecdh_anon

          ``constant` SSL.Constants.`KE_ecdh_anon``

        Description

          Elliptic Curve DH Anonymous

        Constant KE_ecdh_ecdsa

          ``constant` SSL.Constants.`KE_ecdh_ecdsa``

        Description

          Elliptic Curve DH cert signed with ECDSA

        Constant KE_ecdh_rsa

          ``constant` SSL.Constants.`KE_ecdh_rsa``

        Description

          Elliptic Curve DH cert signed with RSA

        Constant KE_ecdhe_ecdsa

          ``constant` SSL.Constants.`KE_ecdhe_ecdsa``

        Description

          Elliptic Curve DH Ephemeral with ECDSA

        Constant KE_ecdhe_rsa

          ``constant` SSL.Constants.`KE_ecdhe_rsa``

        Description

          Elliptic Curve DH Ephemeral with RSA

        Constant KE_null

          ``constant` SSL.Constants.`KE_null``

        Description

          None.

        Constant KE_psk

          ``constant` SSL.Constants.`KE_psk``

        Description

          Preshared Key

        Constant KE_rsa

          ``constant` SSL.Constants.`KE_rsa``

        Description

          Rivest-Shamir-Adelman

        Constant KE_rsa_fips

          ``constant` SSL.Constants.`KE_rsa_fips``

        Description

          Rivest-Shamir-Adelman with FIPS keys.

        Constant KE_rsa_psk

          ``constant` SSL.Constants.`KE_rsa_psk``

        Description

          Preshared Key signed with RSA

        Constant KE_srp_sha

          ``constant` SSL.Constants.`KE_srp_sha``

        Description

          Secure Remote Password (SRP)

        Constant KE_srp_sha_dss

          ``constant` SSL.Constants.`KE_srp_sha_dss``

        Description

          SRP signed with DSS

        Constant KE_srp_sha_rsa

          ``constant` SSL.Constants.`KE_srp_sha_rsa``

        Description

          SRP signed with RSA

      ## Enum SSL.Constants.ProtocolVersion

        Description

          Constants for specifying the versions of SSL/TLS to use.

        See also

          `Context`

        Constant PROTOCOL_SSL_3_0

          ``constant` SSL.Constants.`PROTOCOL_SSL_3_0``

        Description

          SSL 3.0 - The original SSL3 draft version.

        Constant PROTOCOL_SSL_3_1

          ``constant` SSL.Constants.`PROTOCOL_SSL_3_1``

        Description

          SSL 3.1 - The RFC 2246 version of SSL.

        Constant PROTOCOL_SSL_3_2

          ``constant` SSL.Constants.`PROTOCOL_SSL_3_2``

        Description

          SSL 3.2 - The RFC 4346 version of SSL.

        Constant PROTOCOL_SSL_3_3

          ``constant` SSL.Constants.`PROTOCOL_SSL_3_3``

        Description

          SSL 3.3 - The RFC 5246 version of SSL.

        Constant PROTOCOL_TLS_1_0

          ``constant` SSL.Constants.`PROTOCOL_TLS_1_0``

        Description

          TLS 1.0 - The RFC 2246 version of TLS.

        Constant PROTOCOL_TLS_1_1

          ``constant` SSL.Constants.`PROTOCOL_TLS_1_1``

        Description

          TLS 1.1 - The RFC 4346 version of TLS.

        Constant PROTOCOL_TLS_1_2

          ``constant` SSL.Constants.`PROTOCOL_TLS_1_2``

        Description

          TLS 1.2 - The RFC 5246 version of TLS.

      ## Enum SSL.Constants.SignatureAlgorithm

        Description

          Signature algorithms from TLS 1.2.

        Constant SIGNATURE_anonymous

          ``constant` SSL.Constants.`SIGNATURE_anonymous``

        Description

          No signature.

        Constant SIGNATURE_dsa

          ``constant` SSL.Constants.`SIGNATURE_dsa``

        Description

          DSS signature.

        Constant SIGNATURE_ecdsa

          ``constant` SSL.Constants.`SIGNATURE_ecdsa``

        Description

          ECDSA signature.

        Constant SIGNATURE_rsa

          ``constant` SSL.Constants.`SIGNATURE_rsa``

        Description

          RSASSA PKCS1 v1.5 signature.

      ## Class SSL.Constants.CertificatePair

        Description

          A chain of X509 certificates with corresponding private key.

          It also contains some derived metadata.

        Variable cert_type

          ``int` SSL.Constants.CertificatePair.cert_type`

        Description

          Cerificate type for the leaf cert.

          One of the `AUTH_*` constants.

        Variable certs

          ``array`(`string(8bit)`) SSL.Constants.CertificatePair.certs`

        Description

          Chain of certificates, root cert last.

        Method create

          `SSL.Constants.CertificatePair SSL.Constants.CertificatePair(`Crypto.Sign.State` `key`, `array`(`string(8bit)`) `certs`, `array`(`string(8bit)`)|`void` `extra_name_globs`)`

        Description

          Initializa a new `CertificatePair`.

        Parameter `key`

          Private key.

        Parameter `certs`

          Chain of certificates, root cert last.

        Parameter `extra_globs`

          The set of `globs` from the first certificate is optionally extended with these.

        Note

          Performs various validation checks.

        Variable globs

          ``array`(`string(8bit)`) SSL.Constants.CertificatePair.globs`

        Description

          Array of commonName globs from the first certificate in `certs`.

        Variable issuers

          ``array`(`string(8bit)`) SSL.Constants.CertificatePair.issuers`

        Description

          Array of DER for the issuers matching `certs`.

        Variable ke_mask

          ``int(0..)` SSL.Constants.CertificatePair.ke_mask`

        Description

          Bitmask of the key exchange algorithms supported by the main certificate. This is used for TLS 1.1 and earlier.

        See also

          `ke_mask_invariant`

        Variable ke_mask_invariant

          ``int(0..)` SSL.Constants.CertificatePair.ke_mask_invariant`

        Description

          Bitmask of the key exchange algorithms supported by the main certificate. This is the same as `ke_mask`, but unified with respect to `KE_dh_dss`/`KE_dh_rsa` and `KE_ecdh_ecdsa`/`KE_ecdh_rsa`, as supported by TLS 1.2 and later.

        Variable key

          ``Crypto.Sign.State` SSL.Constants.CertificatePair.key`

        Description

          Private key.

        Variable sign_algs

          ``array`(`array`(`HashAlgorithm`|`SignatureAlgorithm`)) SSL.Constants.CertificatePair.sign_algs`

        Description

          TLS 1.2-style hash and signature pairs matching the `certs`.

  ## Module Protocols.LysKOM

    ## Class Protocols.LysKOM.Connection

      Description

        This class contains nice abstraction for calls into the server. They are named "`call`", "`async_call`" or "`async_cb_call`", depending on how you want the call to be done.

      Method XXX
      Method async_XXX
      Method async_cb_XXX

        ``mixed` XXX(`mixed` ... `args`)`
        ``object` async_XXX(`mixed` ... `args`)`
        ``object` async_cb_XXX(`function`(:`void`) `callback`, `mixed` ... `args`)`

      Description

        Do a call to the server. This really clones a `Protocols.LysKOM.Request` object, and initialises it. `XXX` is to be read as one of the calls in the lyskom protocol. ('-' is replaced with '_'.) (ie, logout, async_login or async_cb_get_conf_stat.)

        The first method is a synchronous call. This will send the command, wait for the server to execute it, and then return the result.

        The last two are asynchronous calls, returning an initialised `Protocols.LysKOM.Request` object.

      Method create

        `Protocols.LysKOM.Connection Protocols.LysKOM.Connection(`string` `server`)`
        `Protocols.LysKOM.Connection Protocols.LysKOM.Connection(`string` `server`, `mapping` `options`)`

      Description

        The `options` argument is a mapping with the following members:

        ``"login"` : `int`|`string`` | login as this person number (get number from name).
        ``"password"` : `string`` | send this login password.
        ``"invisible"` : `bool`` | if set, login invisible.
        ``"port"` : `int(16bit)`` | server port (default is 4894).
        ``"whoami"` : `string`` | present as this user (default is from uid/getpwent and hostname).

      Variable protocol_level
      Variable session_software
      Variable software_version

        ``int` Protocols.LysKOM.Connection.protocol_level`
        ``string` Protocols.LysKOM.Connection.session_software`
        ``string` Protocols.LysKOM.Connection.software_version`

      Description

        Description of the connected server.

    ## Class Protocols.LysKOM.Session

      Method conference

        ``Conference` conference(`int` `no`)`

      Description

        Returns conference number `no`.

      Method create

        `Protocols.LysKOM.Session Protocols.LysKOM.Session(`string` `server`)`
        `Protocols.LysKOM.Session Protocols.LysKOM.Session(`string` `server`, `mapping` `options`)`

      Description

        Initializes the session object, and opens a connection to that server.

        `options` is a mapping of options:

        ``"login"` : `int`|`string`` | login as this person number (get number from name).
        ``"create"` : `string`` | create a new person and login with it.
        ``"password"` : `string`` | send this login password.
        ``"invisible"` : `bool`` | if set, login invisible.
        ``"port"` : `int(16bit)`` | server port (default is 4894).
        ``"whoami"` : `string`` | present as this user (default is from uid/getpwent and hostname).

      See also

        `Connection`

      Method create_person

        ``object` create_person(`string` `name`, `string` `password`)`

      Description

        Create a person, which will be logged in. returns the new person object

      Method create_text

        ``object` create_text(`string` `subject`, `string` `body`, `mapping` `options`)`
        ``object` create_text(`string` `subject`, `string` `body`, `mapping` `options`, `function`(:`void`) `callback`, `mixed` ... `extra`)`

      Description

        Creates a new text.

        if `callback` is given, the function will be called when the text has been created, with the text as first argument. Otherwise, the new text is returned.

        `options` is a mapping that may contain:

        ``"recpt"` : `Conference`|`array`(`Conference`)` | recipient conferences.
        ``"cc"` : `Conference`|`array`(`Conference`)` | cc-recipient conferences.
        ``"bcc"` : `Conference`|`array`(`Conference`)` | bcc-recipient conferences*.
        ``"comm_to"` : `Text`|`array`(`Text`)` | The text(s) to be commented.
        ``"foot_to"` : `Text`|`array`(`Text`)` | The text(s) to be footnoted.
        ``"anonymous"` : `bool`` | send text anonymously.
        ``"aux_items"` : `array`(`AuxItemInput`)` | AuxItems you want to set for the text*.

      Note

        The items above marked with '*' are only available on protocol 10 servers. A LysKOM error will be thrown if the call fails.

      See also

        `Conference.create_text()`, `Text.comment()`, `Text.footnote()`

      Method login

        ``object` login(`int` `user_no`, `string` `password`)`
        ``object` login(`int` `user_no`, `string` `password`, `int` `invisible`)`

      Description

        Performs a login. Throws a lyskom error if unsuccessful.

      Returns

        The session object logged in.

      Method logout

        ``this_program` logout()`

      Description

        Logouts from the server. returns the called object

      Method person

        ``Person` person(`int` `no`)`

      Description

        Returns the `Person` `no`.

      Method register_async_message_callback

        ``void` register_async_message_callback(`function`(`int`, `int`, `string`:`void`) `cb`)`

      Method send_message

        ``object`|`void` send_message(`string` `textstring`, `mapping` `options`)`

      Description

        Sends a message.

        `options` is a mapping that may contain:

        ``"recpt"` : `Conference`` | recipient conference.

      Method text

        ``Text` text(`int` `no`)`

      Description

        Returns the text `no`.

      Method try_complete_person

        ``array`(`ProtocolTypes.ConfZInfo`) try_complete_person(`string` `orig`)`

      Description

        Runs a LysKOM completion on the given string, returning an array of confzinfos of the match.

      Variable user

        ``object` Protocols.LysKOM.Session.user`

      Description

        This variable contains the `Protocols.LysKOM.Session.Person` that is logged in.

      ## Class Protocols.LysKOM.Session.AuxItemInput

        FIXME

          Undocumented

        Inherit AuxItemInput

          `inherit ProtocolTypes.AuxItemInput : AuxItemInput`

      ## Class Protocols.LysKOM.Session.AuxItems

        FIXME

          Undocumented

      ## Class Protocols.LysKOM.Session.Conference

        Variable prefetch_stat
        Variable no
        Variable error
        Variable msg_of_day
        Variable supervisor
        Variable permitted_submitters
        Variable super_conf
        Variable creator
        Variable aux_items
        Variable name
        Variable type
        Variable creation_time
        Variable last_written
        Variable nice
        Variable no_of_members
        Variable first_local_no
        Variable no_of_texts
        Variable presentation

          ``mixed` Protocols.LysKOM.Session.Conference.prefetch_stat`
          ``int` Protocols.LysKOM.Session.Conference.no`
          ``object` Protocols.LysKOM.Session.Conference.error`
          ``Text` Protocols.LysKOM.Session.Conference.msg_of_day`
          ``Conference` Protocols.LysKOM.Session.Conference.supervisor`
          ``Conference` Protocols.LysKOM.Session.Conference.permitted_submitters`
          ``Conference` Protocols.LysKOM.Session.Conference.super_conf`
          ``Person` Protocols.LysKOM.Session.Conference.creator`
          ``mixed` Protocols.LysKOM.Session.Conference.aux_items`
          ``mixed` Protocols.LysKOM.Session.Conference.name`
          ``mixed` Protocols.LysKOM.Session.Conference.type`
          ``mixed` Protocols.LysKOM.Session.Conference.creation_time`
          ``mixed` Protocols.LysKOM.Session.Conference.last_written`
          ``mixed` Protocols.LysKOM.Session.Conference.nice`
          ``mixed` Protocols.LysKOM.Session.Conference.no_of_members`
          ``mixed` Protocols.LysKOM.Session.Conference.first_local_no`
          ``mixed` Protocols.LysKOM.Session.Conference.no_of_texts`
          ``mixed` Protocols.LysKOM.Session.Conference.presentation`

        FIXME

          Undocumented

        Method create

          `Protocols.LysKOM.Session.Conference Protocols.LysKOM.Session.Conference(`int` `no`)`

      ## Class Protocols.LysKOM.Session.Membership

        Description

          All variables in this class is read only.

        Variable added_at

          ``object` Protocols.LysKOM.Session.Membership.added_at`

        Variable conf

          ``object` Protocols.LysKOM.Session.Membership.conf`

        Variable last_text_read

          ``int` Protocols.LysKOM.Session.Membership.last_text_read`

        Variable last_time_read

          ``object` Protocols.LysKOM.Session.Membership.last_time_read`

        Method number_unread

          ``int` number_unread()`

        Variable position

          ``int` Protocols.LysKOM.Session.Membership.position`

        Variable priority

          ``int(8bit)` Protocols.LysKOM.Session.Membership.priority`

        Method query_read_texts

          ``void` query_read_texts()`

        Variable read_texts

          ``array`(`int`) Protocols.LysKOM.Session.Membership.read_texts`

        Variable type

          ``multiset`(`string`) Protocols.LysKOM.Session.Membership.type`

        Method unread_texts

          ``array`(`object`) unread_texts()`

      ## Class Protocols.LysKOM.Session.Person

        Variable error
        Variable user_area
        Variable username
        Variable privileges
        Variable flags
        Variable last_login
        Variable total_time_present
        Variable sessions
        Variable created_lines
        Variable created_bytes
        Variable read_texts
        Variable no_of_text_fetches
        Variable created_persons
        Variable created_confs
        Variable first_created_local_no
        Variable no_of_created_texts
        Variable no_of_marks
        Variable no_of_confs
        Variable unread
        Variable clear_membership
        Variable membership

          ``object` Protocols.LysKOM.Session.Person.error`
          ``Text` Protocols.LysKOM.Session.Person.user_area`
          ``mixed` Protocols.LysKOM.Session.Person.username`
          ``mixed` Protocols.LysKOM.Session.Person.privileges`
          ``mixed` Protocols.LysKOM.Session.Person.flags`
          ``mixed` Protocols.LysKOM.Session.Person.last_login`
          ``mixed` Protocols.LysKOM.Session.Person.total_time_present`
          ``mixed` Protocols.LysKOM.Session.Person.sessions`
          ``mixed` Protocols.LysKOM.Session.Person.created_lines`
          ``mixed` Protocols.LysKOM.Session.Person.created_bytes`
          ``mixed` Protocols.LysKOM.Session.Person.read_texts`
          ``mixed` Protocols.LysKOM.Session.Person.no_of_text_fetches`
          ``mixed` Protocols.LysKOM.Session.Person.created_persons`
          ``mixed` Protocols.LysKOM.Session.Person.created_confs`
          ``mixed` Protocols.LysKOM.Session.Person.first_created_local_no`
          ``mixed` Protocols.LysKOM.Session.Person.no_of_created_texts`
          ``mixed` Protocols.LysKOM.Session.Person.no_of_marks`
          ``mixed` Protocols.LysKOM.Session.Person.no_of_confs`
          ``mixed` Protocols.LysKOM.Session.Person.unread`
          ``int(0..0)` Protocols.LysKOM.Session.Person.clear_membership`
          ``mixed` Protocols.LysKOM.Session.Person.membership`

        FIXME

          Undocumented

        Method create

          `Protocols.LysKOM.Session.Person Protocols.LysKOM.Session.Person(`int` `no`)`

        Variable no

          ``int` Protocols.LysKOM.Session.Person.no`

        Variable prefetch_stat
        Variable prefetch_conf
        Variable prefetch_membership

          ``mixed` Protocols.LysKOM.Session.Person.prefetch_stat`
          ``mixed` Protocols.LysKOM.Session.Person.prefetch_conf`
          ``mixed` Protocols.LysKOM.Session.Person.prefetch_membership`

        FIXME

          Undocumented

      ## Class Protocols.LysKOM.Session.Text

        Description

          All variables in this class is read only.

        FIXME

          Undocumented

        Variable author

          ``string` Protocols.LysKOM.Session.Text.author`

        Description

          The author of the text.

        Variable prefetch_text
        Variable prefetch_stat
        Variable lines
        Variable characters
        Variable clear_stat
        Variable aux_items

          ``mixed` Protocols.LysKOM.Session.Text.prefetch_text`
          ``mixed` Protocols.LysKOM.Session.Text.prefetch_stat`
          ``mixed` Protocols.LysKOM.Session.Text.lines`
          ``mixed` Protocols.LysKOM.Session.Text.characters`
          ``mixed` Protocols.LysKOM.Session.Text.clear_stat`
          ``mixed` Protocols.LysKOM.Session.Text.aux_items`

        FIXME

          Undocumented

        Method create

          `Protocols.LysKOM.Session.Text Protocols.LysKOM.Session.Text(`string` `textnumber`)`

        Description

          Initializes a Text object.

        Variable creation_time

          ``mixed` Protocols.LysKOM.Session.Text.creation_time`

        Description

          The time the text was created on the server.

        Variable err

          ``object` Protocols.LysKOM.Session.Text.err`

        Description

          Undocumented

        Method mark_as_read

          ``void` mark_as_read()`

        FIXME

          Undocumented.

        Variable marks

          ``int` Protocols.LysKOM.Session.Text.marks`

        Description

          The number of marks on this text.

        Variable misc

          ``mixed` Protocols.LysKOM.Session.Text.misc`

        Description

          Misc info, including what conferences the message is posted to.

        FIXME

          Needs a more complete description.

        Variable no

          ``int` Protocols.LysKOM.Session.Text.no`

        Description

          The text number, as spicified to `create`.

        Variable subject

          ``string` Protocols.LysKOM.Session.Text.subject`

        Description

          The message subject.

        Variable text

          ``string` Protocols.LysKOM.Session.Text.text`

        Description

          The actual text (or body if you wish).

    ## Module Protocols.LysKOM.ProtocolTypes

      Description

        Data types as defined by the LysKOM protocol specification.

    ## Module Protocols.LysKOM.Request

      Description

        This module contains nice abstraction for calls into the server. They are named "`call`", "`async_call`" or "`async_cb_call`", depending on how you want the call to be done.

      ## Class Protocols.LysKOM.Request._Request

        Description

          This is the main request class. All lyskom request classes inherit this class.

        Method _async
        Method _sync

          ``void` _async(`int` `call`, `mixed_data`)`
          ``mixed` _sync(`int` `call`, `mixed_data`)`

        Description

          Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. These are called by async and sync respectively.

        Method _reply
        Method reply

          ``mixed` _reply(`object`|`array` `what`)`
          ``mixed` reply(`object`|`array` `what`)`

        Description

          `_reply()` is called as callback to evaluate the result, and calls `reply()` in itself to do the real work.

        Method `()

          ``mixed` res = `Protocols.LysKOM.Request._Request()`()`

        Description

          Wait for the call to finish.

        Method async
        Method sync

          ``void` async(`mixed` ... `args`)`
          ``mixed` sync(`mixed` ... `args`)`

        Description

          Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. This calls `indata()` in itself, to get the correct arguments to the lyskom protocol call.

        Variable error

          ``object` Protocols.LysKOM.Request._Request.error`

        Description

          How the call failed. The call has completed if `(ok||error)`.

        Variable ok

          ``bool` Protocols.LysKOM.Request._Request.ok`

        Description

          Tells if the call has executed ok

  ## Module Protocols.DNS

    Description

      Support for the Domain Name System protocol.

      RFC 1034, RFC 1035 and RFC 2308

    Constant FORMERR

      ```final` constant` `int` Protocols.DNS.`FORMERR``

    Description

      The name server was unable to interpret the request due to a format error.

    Constant NOERROR

      ```final` constant` `int` Protocols.DNS.`NOERROR``

    Description

      No error condition.

    Constant NOTIMPL

      ```final` constant` `int` Protocols.DNS.`NOTIMPL``

    Description

      The name server does not support the specified Opcode.

    Constant NXDOMAIN

      ```final` constant` `int` Protocols.DNS.`NXDOMAIN``

    Description

      Some name that ought to exist, does not exist.

    Constant NXRRSET

      ```final` constant` `int` Protocols.DNS.`NXRRSET``

    Description

      Some RRset that ought to exist, does not exist.

    Constant REFUSED

      ```final` constant` `int` Protocols.DNS.`REFUSED``

    Description

      The name server refuses to perform the specified operation for policy or security reasons.

    Constant SERVFAIL

      ```final` constant` `int` Protocols.DNS.`SERVFAIL``

    Description

      The name server encountered an internal failure while processing this request, for example an operating system error or a forwarding timeout.

    Method async_get_mx

      ``void` async_get_mx(`string` `host`, `function`(:`void`) `cb`, `mixed` ... `cba`)`

    Method async_get_mx_all

      ``void` async_get_mx_all(`string` `host`, `function`(:`void`) `cb`, `mixed` ... `cba`)`

    Method async_host_to_ip

      ``void` async_host_to_ip(`string` `host`, `function`(:`void`) `cb`, `mixed` ... `cba`)`

    Method async_ip_to_host

      ``void` async_ip_to_host(`string` `ip`, `function`(:`void`) `cb`, `mixed` ... `cba`)`

    Method get_mx

      ``string` get_mx(`string` `host`)`

    Method get_primary_mx

      ``string` get_primary_mx(`string` `host`)`

    Method gethostbyaddr

      ``array` gethostbyaddr(`string` `host`)`

    Method gethostbyname

      ``array` gethostbyname(`string` `host`)`

    ## Enum Protocols.DNS.EntryType

      Description

        Entry types

      Constant T_A

        ``constant` Protocols.DNS.`T_A``

      Description

        Type - host address

      Constant T_A6

        ``constant` Protocols.DNS.`T_A6``

      Description

        Type - IPv6 address record (RFC 2874 Obsolete RFC 6563)

      Constant T_AAAA

        ``constant` Protocols.DNS.`T_AAAA``

      Description

        Type - IPv6 address record (RFC 1886)

      Constant T_AFSDB

        ``constant` Protocols.DNS.`T_AFSDB``

      Description

        Type - AFC database record (RFC 1183)

      Constant T_ANY

        ``constant` Protocols.DNS.`T_ANY``

      Description

        Type - ANY - A request for all records

      Constant T_APL

        ``constant` Protocols.DNS.`T_APL``

      Description

        Type - Address Prefix List (RFC 3123)

      Constant T_ATMA

        ``constant` Protocols.DNS.`T_ATMA``

      Description

        Type - ATM End System Address (af-saa-0069.000)

      Constant T_AXFR

        ``constant` Protocols.DNS.`T_AXFR``

      Description

        Type - Authoritative Zone Transfer (RFC 1035)

      Constant T_CAA

        ``constant` Protocols.DNS.`T_CAA``

      Description

        Type - Certificate Authority Authorization (RFC 6844)

      Constant T_CERT

        ``constant` Protocols.DNS.`T_CERT``

      Description

        Type - Certificate Record (RFC 4398)

      Constant T_CNAME

        ``constant` Protocols.DNS.`T_CNAME``

      Description

        Type - canonical name for an alias

      Constant T_DHCID

        ``constant` Protocols.DNS.`T_DHCID``

      Description

        Type - DHCP identifier (RFC 4701)

      Constant T_DLV

        ``constant` Protocols.DNS.`T_DLV``

      Description

        Type - DNSSEC Lookaside Validation Record (RFC 4431)

      Constant T_DNAME

        ``constant` Protocols.DNS.`T_DNAME``

      Description

        Type - Delegation Name (RFC 2672)

      Constant T_DNSKEY

        ``constant` Protocols.DNS.`T_DNSKEY``

      Description

        Type - DNS Key record (RFC 4034)

      Constant T_DS

        ``constant` Protocols.DNS.`T_DS``

      Description

        Type - Delegation Signer (RFC 4034)

      Constant T_EID

        ``constant` Protocols.DNS.`T_EID``

      Description

        Type - Nimrod Endpoint IDentifier (draft)

      Constant T_GPOS

        ``constant` Protocols.DNS.`T_GPOS``

      Description

        Type - Global Position (RFC 1712 Obsolete use LOC).

      Constant T_HINFO

        ``constant` Protocols.DNS.`T_HINFO``

      Description

        Type - host information

      Constant T_HIP

        ``constant` Protocols.DNS.`T_HIP``

      Description

        Type - Host Identity Protocol (RFC 5205)

      Constant T_IPSECKEY

        ``constant` Protocols.DNS.`T_IPSECKEY``

      Description

        Type - IPsec Key (RFC 4025)

      Constant T_ISDN

        ``constant` Protocols.DNS.`T_ISDN``

      Description

        Type - ISDN address (RFC 1183)

      Constant T_IXFR

        ``constant` Protocols.DNS.`T_IXFR``

      Description

        Type - Incremental Zone Transfer (RFC 1996)

      Constant T_KEY

        ``constant` Protocols.DNS.`T_KEY``

      Description

        Type - Key record (RFC 2535 and RFC 2930)

      Constant T_KX

        ``constant` Protocols.DNS.`T_KX``

      Description

        Type - Key eXchanger record (RFC 2230)

      Constant T_LOC

        ``constant` Protocols.DNS.`T_LOC``

      Description

        Type - Location Record (RFC 1876)

      Constant T_MAILA

        ``constant` Protocols.DNS.`T_MAILA``

      Description

        Type - Mail Agent (both MD and MF) (Obsolete - use MX)

      Constant T_MAILB

        ``constant` Protocols.DNS.`T_MAILB``

      Description

        Type - Mail Box (MB, MG or MR) (Obsolete - use MX)

      Constant T_MB

        ``constant` Protocols.DNS.`T_MB``

      Description

        Type - mailbox domain name (Obsolete)

      Constant T_MD

        ``constant` Protocols.DNS.`T_MD``

      Description

        Type - mail destination (Obsolete - use MX)

      Constant T_MF

        ``constant` Protocols.DNS.`T_MF``

      Description

        Type - mail forwarder (Obsolete - use MX)

      Constant T_MG

        ``constant` Protocols.DNS.`T_MG``

      Description

        Type - mail group member (Obsolete)

      Constant T_MINFO

        ``constant` Protocols.DNS.`T_MINFO``

      Description

        Type - mailbox or mail list information (Obsolete)

      Constant T_MR

        ``constant` Protocols.DNS.`T_MR``

      Description

        Type - mail rename domain name (Obsolete)

      Constant T_MX

        ``constant` Protocols.DNS.`T_MX``

      Description

        Type - mail exchange

      Constant T_NAPTR

        ``constant` Protocols.DNS.`T_NAPTR``

      Description

        Type - NAPTR (RFC 3403)

      Constant T_NIMLOC

        ``constant` Protocols.DNS.`T_NIMLOC``

      Description

        Type - Nimrod Locator (draft)

      Constant T_NS

        ``constant` Protocols.DNS.`T_NS``

      Description

        Type - authoritative name server

      Constant T_NSAP

        ``constant` Protocols.DNS.`T_NSAP``

      Description

        Type - OSI Network Service Access Protocol (RFC 1348, RFC 1637, RFC 1706)

      Constant T_NSAP_PTR

        ``constant` Protocols.DNS.`T_NSAP_PTR``

      Description

        Type - OSI NSAP Pointer (RFC 1348, Obsolete RFC 1637)

      Constant T_NSEC

        ``constant` Protocols.DNS.`T_NSEC``

      Description

        Type - Next-Secure record (RFC 4034)

      Constant T_NSEC3

        ``constant` Protocols.DNS.`T_NSEC3``

      Description

        Type - NSEC record version 3 (RFC 5155)

      Constant T_NSEC3PARAM

        ``constant` Protocols.DNS.`T_NSEC3PARAM``

      Description

        Type - NSEC3 parameters (RFC 5155)

      Constant T_NULL

        ``constant` Protocols.DNS.`T_NULL``

      Description

        Type - null RR (Obsolete RFC 1035)

      Constant T_NXT

        ``constant` Protocols.DNS.`T_NXT``

      Description

        Type - Next (RFC 2065, Obsolete RFC 3755)

      Constant T_OPT

        ``constant` Protocols.DNS.`T_OPT``

      Description

        Type - Option (RFC 2671)

      Constant T_PTR

        ``constant` Protocols.DNS.`T_PTR``

      Description

        Type - domain name pointer

      Constant T_PX

        ``constant` Protocols.DNS.`T_PX``

      Description

        Type - Pointer to X.400 mapping information (RFC 1664)

      Constant T_RP

        ``constant` Protocols.DNS.`T_RP``

      Description

        Type - Responsible Person

      Constant T_RRSIG

        ``constant` Protocols.DNS.`T_RRSIG``

      Description

        Type - DNSSEC signature (RFC 4034)

      Constant T_RT

        ``constant` Protocols.DNS.`T_RT``

      Description

        Type - Route Through (RFC 1183)

      Constant T_SIG

        ``constant` Protocols.DNS.`T_SIG``

      Description

        Type - Signature (RFC 2535)

      Constant T_SINK

        ``constant` Protocols.DNS.`T_SINK``

      Description

        Type - Kitchen Sink (draft)

      Constant T_SOA

        ``constant` Protocols.DNS.`T_SOA``

      Description

        Type - start of a zone of authority

      Constant T_SPF

        ``constant` Protocols.DNS.`T_SPF``

      Description

        Type - SPF - Sender Policy Framework (RFC 4408)

      Constant T_SRV

        ``constant` Protocols.DNS.`T_SRV``

      Description

        Type - Service location record (RFC 2782)

      Constant T_SSHFP

        ``constant` Protocols.DNS.`T_SSHFP``

      Description

        Type - SSH Public Key Fingerprint (RFC 4255)

      Constant T_TA

        ``constant` Protocols.DNS.`T_TA``

      Description

        Type - DNSSEC Trust Authorities (draft)

      Constant T_TKEY

        ``constant` Protocols.DNS.`T_TKEY``

      Description

        Type - Secret key record (RFC 2930)

      Constant T_TLSA

        ``constant` Protocols.DNS.`T_TLSA``

      Description

        Type - TLSA certificate association (RFC 6698)

      Constant T_TSIG

        ``constant` Protocols.DNS.`T_TSIG``

      Description

        Type - Transaction Signature (RFC 2845)

      Constant T_TXT

        ``constant` Protocols.DNS.`T_TXT``

      Description

        Type - text strings

      Constant T_WKS

        ``constant` Protocols.DNS.`T_WKS``

      Description

        Type - well known service description (Obsolete RFC 1123, RFC 1127)

      Constant T_X25

        ``constant` Protocols.DNS.`T_X25``

      Description

        Type - X25 PSDN address (RFC 1183)

    ## Enum Protocols.DNS.ResourceClass

      Description

        Resource classes

      Constant C_ANY

        ``constant` Protocols.DNS.`C_ANY``

      Description

        Class ANY

      Constant C_CH

        ``constant` Protocols.DNS.`C_CH``

      Description

        Class CHAOS

      Constant C_CS

        ``constant` Protocols.DNS.`C_CS``

      Description

        Class CSNET (Obsolete)

      Constant C_HS

        ``constant` Protocols.DNS.`C_HS``

      Description

        Class Hesiod

      Constant C_IN

        ``constant` Protocols.DNS.`C_IN``

      Description

        Class Internet

    ## Class Protocols.DNS.async_client

      Description

        Asynchronous DNS client.

      Method close

        ``void` close()`

      Description

        Close the client.

      Note

        All active requests are aborted.

      Method create

        `Protocols.DNS.async_client Protocols.DNS.async_client(`void`|`string`|`array`(`string`) `server`, `void`|`string`|`array`(`string`) `domain`)`

      Method do_query

        ``Request` do_query(`string` `domain`, `int` `cl`, `int` `type`, `function`(`string`, `mapping`, `mixed` ... :`void`) `callback`, `mixed` ... `args`)`

      Description

        Enqueue a new raw DNS request.

      Returns

        Returns a `Request` object.

      Note

        Pike versions prior to 8.0 did not return the `Request` object.

      Method get_mx

        ``Request` get_mx(`string` `host`, `function`(:`void`) `callback`, `mixed` ... `args`)`

      Method get_mx_all

        ``Request` get_mx_all(`string` `host`, `function`(:`void`) `callback`, `mixed` ... `args`)`

      Method host_to_ip

        ``Request` host_to_ip(`string` `host`, `function`(:`void`) `callback`, `mixed` ... `args`)`

      Inherit client

        `inherit client : client`

      Inherit udp

        `inherit Stdio.UDP : udp`

      Method ip_to_host

        ``Request` ip_to_host(`string` `ip`, `function`(:`void`) `callback`, `mixed` ... `args`)`

    ## Class Protocols.DNS.async_dual_client

      Description

        Both an `async_client` and an `async_tcp_client`.

      Method do_query

        ``Request` do_query(`string` `domain`, `int` `cl`, `int` `type`, `function`(`string`, `mapping`, `mixed` ... :`void`) `callback`, `mixed` ... `args`)`

      Inherit TCP

        `inherit async_tcp_client : TCP`

      Inherit UDP

        `inherit async_client : UDP`

    ## Class Protocols.DNS.async_tcp_client

      Description

        Asynchronous DNS client using TCP

      Method do_query

        ``Request` do_query(`string` `domain`, `int` `cl`, `int` `type`, `function`(`string`, `mapping`, `mixed` ... :`void`) `callback`, `mixed` ... `args`)`

      Inherit async_client

        `inherit async_client : async_client`

      ## Class Protocols.DNS.async_tcp_client.Request

        Inherit this_program

          `inherit ::this_program : this_program`

    ## Class Protocols.DNS.client

      Description

        Synchronous DNS client.

      Method create

        `Protocols.DNS.client Protocols.DNS.client()`
        `Protocols.DNS.client Protocols.DNS.client(`void`|`string`|`array` `server`, `void`|`int`|`array` `domain`)`

      Method do_sync_query

        ``mapping` do_sync_query(`string` `s`)`

      Description

        Perform a synchronous DNS query.

      Parameter `s`

        Result of `Protocols.DNS.protocol.mkquery`

      Returns

        mapping containing query result or 0 on failure/timeout

      Example

            // Perform a hostname lookup, results stored in r->an
                object d=Protocols.DNS.client();
                mapping r=d->do_sync_query(d->mkquery("pike.lysator.liu.se", C_IN, T_A));

      Method get_mx

        ``array`(`string`) get_mx(`string` `host`)`

      Method get_primary_mx

        ``string` get_primary_mx(`string` `hostname`)`

      Description

        Queries the primary mx for the host.

      Returns

        Returns the hostname of the primary mail exchanger.

      Method gethostbyaddr

        ``array` gethostbyaddr(`string` `hostip`)`

      Description

        Queries the host name or ip from the default or given DNS server. The result is an array with three elements,

      Returns

        The requested data about the specified host.

        Array
        ``string` `hostip`` | The host IP.
        ``array`(`string`) `ip`` | IP number(s).
        ``array`(`string`) `aliases`` | DNS name(s).

      Method gethostbyname

        ``array` gethostbyname(`string` `hostname`)`

      Description

        Queries the host name from the default or given DNS server. The result is an array with three elements,

      Returns

        An array with the requested information about the specified host.

        Array
        ``string` `hostname`` | Hostname.
        ``array`(`string`) `ip`` | IP number(s).
        ``array`(`string`) `aliases`` | DNS name(s).

      Note

        Prior to Pike 7.7 this function only returned IPv4 addresses.

      Method getsrvbyname

        ``array` getsrvbyname(`string` `service`, `string` `protocol`, `string`|`void` `name`)`

      Description

        Queries the service record (RFC 2782) from the default or given DNS server. The result is an array of arrays with the following six elements for each record. The array is sorted according to the priority of each record.

        Each element of the array returned represents a service record. Each service record contains the following:

      Returns

        An array with the requested information about the specified service.

        Array
        ``int` `priority`` | Priority
        ``int` `weight`` | Weight in event of multiple records with same priority.
        ``int` `port`` | port number
        ``string` `target`` | target dns name

      Inherit protocol

        `inherit protocol : protocol`

      ## Class Protocols.DNS.client.Request

        Variable domain
        Variable req
        Variable callback
        Variable args

          ``string` Protocols.DNS.client.Request.domain`
          ``string` Protocols.DNS.client.Request.req`
          ``function`(`string`, `mapping`, `mixed` ... :`void`) Protocols.DNS.client.Request.callback`
          ``array`(`mixed`) Protocols.DNS.client.Request.args`

        Syntax

          ``void` cancel()```mixed` Protocols.DNS.client.Request.retry_co`

        Description

          Cancel the current request.

        Method create

          `Protocols.DNS.client.Request Protocols.DNS.client.Request(`string` `domain`, `string` `req`, `function`(`string`, `mapping`, `mixed` ... :`void`) `callback`, `array`(`mixed`) `args`)`

    ## Class Protocols.DNS.dual_client

      Description

        Both a `client` and a `tcp_client`.

      Method do_sync_query

        ``mapping` do_sync_query(`string` `s`)`

      Inherit TCP

        `inherit tcp_client : TCP`

      Inherit UDP

        `inherit client : UDP`

    ## Class Protocols.DNS.dual_server

      Description

        This is both a `server` and `tcp_server`.

      Inherit TCP

        `inherit tcp_server : TCP`

      Inherit UDP

        `inherit server : UDP`

    ## Class Protocols.DNS.protocol

      Description

        Low level DNS protocol

      Method decode_entries

        ``array` decode_entries(`string` `s`, `int` `num`, `array`(`int`) `next`)`

      Description

        Decode a set of entries from an answer.

      Parameter `s`

        Encoded entries.

      Parameter `num`

        Number of entires in `s`.

      Parameter `next`

        Array with a single element containing the start position in `s` on entry and the continuation position on return.

      Returns

        Returns an array of mappings describing the decoded entires:

        Array

        ``mapping` `0..``

        Mapping describing a single entry:

        ``"name"` : `string`` | Name the entry concerns.
        ``"type"` : `EntryType`` | Type of entry.
        ``"cl"` : `ResourceClass`` | Resource class. Typically `C_IN`.
        ``"ttl"` : `int`` | Time to live for the entry in seconds.
        ``"len"` : `int`` | Length in bytes of the encoded data section.

        Depending on the type of entry the mapping may contain different additional fields:

        ``T_CNAME``

        ``"cname"` : `string``

        ``T_PTR``

        ``"ptr"` : `string``

        ``T_NS``

        ``"ns"` : `string``

        ``T_MX``

        ``"preference"` : `int``
        ``"mx"` : `string``

        ``T_HINFO``

        ``"cpu"` : `string``
        ``"os"` : `string``

        ``T_SRV``

        RFC 2052 and RFC 2782.

        ``"priority"` : `int``
        ``"weight"` : `int``
        ``"port"` : `int``
        ``"target"` : `string``
        ``"service"` : `string``
        ``"proto"` : `string``
        ``"name"` : `string``

        ``T_A``

        ``"a"` : `string`` | IPv4-address in dotted-decimal format.

        ``T_AAAA``

        ``"aaaa"` : `string`` | IPv6-address in colon-separated hexadecimal format.

        ``T_LOC``

        ``"version"` : `int`` | Version, currently only version `0` (zero) is supported.
        ``"size"` : `int`` |
        ``"h_perc"` : `int`` |
        ``"v_perc"` : `int`` |
        ``"lat"` : `int`` |
        ``"long"` : `int`` |
        ``"alt"` : `int`` |

        ``T_SOA``

        ``"mname"` : `string`` |
        ``"rname"` : `string`` |
        ``"serial"` : `int`` |
        ``"refresh"` : `int`` |
        ``"retry"` : `int`` |
        ``"expire"` : `int`` |
        ``"minimum"` : `int`` | Note: For historical reasons this entry is named `"minimum"`, but it contains the TTL for negative answers (RFC 2308).

        ``T_NAPTR``

        ``"order"` : `int``
        ``"preference"` : `int``
        ``"flags"` : `string``
        ``"service"` : `string``
        ``"regexp"` : `string``
        ``"replacement"` : `string``

        ``T_TXT``

        ``"txt"` : `string`` | Note: For historical reasons, when receiving decoded DNS entries from a client, this will be the first string in the TXT record only.
        ``"txta"` : `string`` | When receiving decoded DNS data from a client, txta is the array of all strings in the record. When sending multiple strings in a TXT record in a server, please supply an array as "txt" containing the strings, txta will be ignored.

        ``T_SPF``

        ``"spf"` : `string``

      Method mkquery

        ``string` mkquery(`string`|`mapping` `dnameorquery`, `int`|`void` `cl`, `int`|`void` `type`)`

      Description

        create a DNS query PDU

      Parameter `dnameorquery`
      Parameter `cl`

        record class such as Protocols.DNS.C_IN

      Parameter `type`

        query type such Protocols.DNS.T_A

      Returns

        data suitable for use with `Protocols.DNS.client.do_sync_query`

      Example

            // generate a query PDU for a address lookup on the hostname pike.lysator.liu.se
             string q=Protocols.DNS.protocol()->mkquery("pike.lysator.liu.se", Protocols.DNS.C_IN, Protocols.DNS.T_A);

    ## Class Protocols.DNS.server

      Description

        Base class for implementing a Domain Name Service (DNS) server operating over UDP.

        This class is typically used by inheriting it, and overloading `reply_query()` and `handle_response()`.

      See also

        `dual_server`

      Method create

        `Protocols.DNS.server Protocols.DNS.server()`
        `Protocols.DNS.server Protocols.DNS.server(`int` `port`)`
        `Protocols.DNS.server Protocols.DNS.server(`string` `ip`)`
        `Protocols.DNS.server Protocols.DNS.server(`string` `ip`, `int` `port`)`
        `Protocols.DNS.server Protocols.DNS.server(`string` `ip`, `int` `port`, `string`|`int` ... `more`)`

      Description

        Open one or more new DNS server ports.

      Parameter `ip`

        The IP to bind to. Defaults to `"::"` or `0` (ie ANY) depending on whether IPv6 support is present or not.

      Parameter `port`

        The port number to bind to. Defaults to `53`.

      Parameter `more`

        Optional further DNS server ports to open. Must be a set of `ip`, `port` argument pairs.

      Inherit server_base

        `inherit server_base : server_base`

    ## Class Protocols.DNS.server_base

      Description

        Base class for `server`, `tcp_server`.

      Method handle_decode_error

        ``protected` `void` handle_decode_error(`mapping` `err`, `mapping` `m`, `Stdio.UDP`|`object` `udp`)`

      Description

        Respond to a query that cannot be decoded.

        This method exists so that servers can override the default behaviour.

      Method handle_query

        ``protected` `void` handle_query(`mapping` `q`, `mapping` `m`, `Stdio.UDP`|`object` `udp`)`

      Description

        Handle a query.

        This function calls `reply_query()`, and dispatches the result to `send_reply()`.

      Method handle_response

        ``protected` `void` handle_response(`mapping` `r`, `mapping` `m`, `Stdio.UDP`|`object` `udp`)`

      Description

        Handle a query response (stub).

        Overload this function to handle responses to possible recursive queries.

      Inherit protocol

        `inherit protocol : protocol`

      Method rec_data

        ``protected` `void` rec_data(`mapping` `m`, `Stdio.UDP`|`object` `udp`)`

      Description

        Low-level DNS-data receiver.

        This function receives the raw DNS-data from the `Stdio.UDP` socket or TCP connection object `udp`, decodes it, and dispatches the decoded DNS request to `handle_query()` and `handle_response()`.

      Method reply_query

        ``protected` `mapping` reply_query(`mapping` `query`, `mapping` `udp_data`, `function`(`mapping`:`void`) `cb`)`

      Description

        Reply to a query (stub).

      Parameter `query`

        Parsed query.

      Parameter `udp_data`

        Raw UDP data. If the server operates in TCP mode (`tcp_server`), it will contain an additional tcp_con entry. In that case, `udp_data->tcp_con->con` will contain the TCP connection the request was received on as `Stdio.File` object.

      Parameter `cb`

        Callback you can call with the result instead of returning it. In that case, return `0` (zero).

        Overload this function to implement the proper lookup.

      Note

        To indicate the default failure `cb` must be called with an argument of `0` (zero), and `0` (zero) be returned.

      Returns

        Returns `0` (zero) when the `cb` callback will be used, or a result mapping if not:

        ``"rcode"` : `int`` | 0 (or omit) for success, otherwise one of the Protocols.DNS.* constants

        ``"an"` : `array`(`mapping`(`string`:`string`|`int`))|`void``

        Answer section:

        Array

        ``mapping`(`string`:`string`|`int`) `entry``

        ``"name"` : `string`|`array`(`string`)`
        ``"type"` : `int``
        ``"cl"` : `int``

        ``"qd"` : `array`|`void`` | Question section, same format as `an`; omit to return the original question
        ``"ns"` : `array`|`void`` | Authority section (usually NS records), same format as `an`
        ``"ar"` : `array`|`void`` | Additional section, same format as `an`
        ``"aa"` : `int`` | Set to 1 to include the Authoritative Answer bit in the response
        ``"tc"` : `int`` | Set to 1 to include the TrunCated bit in the response
        ``"rd"` : `int`` | Set to 1 to include the Recursion Desired bit in the response
        ``"ra"` : `int`` | Set to 1 to include the Recursion Available bit in the response
        ``"cd"` : `int`` | Set to 1 to include the Checking Disabled bit in the response
        ``"ad"` : `int`` | Set to 1 to include the Authenticated Data bit in the response

      Method report_decode_error

        ``protected` `void` report_decode_error(`mixed` `err`, `mapping` `m`, `Stdio.UDP`|`object` `udp`)`

      Description

        Report a failure to decode a DNS request.

        The default implementation writes a backtrace to stderr. This method exists so that derived servers can replace it with more appropriate error handling for their environment.

    ## Class Protocols.DNS.tcp_client

      Description

        Synchronous DNS client using TCP Can handle larger responses than `client` can.

      Method do_sync_query

        ``mapping` do_sync_query(`string` `s`)`

      Description

        Perform a synchronous DNS query.

      Parameter `s`

        Result of `Protocols.DNS.protocol.mkquery`

      Returns

        mapping containing query result or 0 on failure/timeout

      Example

            // Perform a hostname lookup, results stored in r->an
                object d=Protocols.DNS.tcp_client();
                mapping r=d->do_sync_query(d->mkquery("pike.lysator.liu.se", C_IN, T_A));

      Inherit client

        `inherit client : client`

    ## Class Protocols.DNS.tcp_server

      Description

        Base class for implementing a Domain Name Service (DNS) server operating over TCP.

        This class is typically used by inheriting it, and overloading `reply_query()` and `handle_response()`.

      Method create

        `Protocols.DNS.tcp_server Protocols.DNS.tcp_server()`
        `Protocols.DNS.tcp_server Protocols.DNS.tcp_server(`int` `port`)`
        `Protocols.DNS.tcp_server Protocols.DNS.tcp_server(`string` `ip`)`
        `Protocols.DNS.tcp_server Protocols.DNS.tcp_server(`string` `ip`, `int` `port`)`
        `Protocols.DNS.tcp_server Protocols.DNS.tcp_server(`string` `ip`, `int` `port`, `string`|`int` ... `more`)`

      Description

        Open one or more new DNS server ports.

      Parameter `ip`

        The IP to bind to. Defaults to `"::"` or `0` (ie ANY) depending on whether IPv6 support is present or not.

      Parameter `port`

        The port number to bind to. Defaults to `53`.

      Parameter `more`

        Optional further DNS server ports to open. Must be a set of `ip`, `port` argument pairs.

      Inherit server_base

        `inherit server_base : server_base`

  ## Module Protocols

    ## Module Protocols.Bittorrent

      ## Class Protocols.Bittorrent.Generator

        Description

          Generate a .torrent binary string from files in the filesystem

        Example

              // usage: thisprogram [<file/dir>] [<file/dir>...] <target .torrent>
                 int main(int ac,array am)
                 {
                    Generator g=Generator();
                    foreach (am[1..<1];;string f)
                       g->add(f);
                    string dest=am[-1];
                    if (-1==search(dest,"torrent")) dest+=".torrent";
                    Stdio.write_file(dest,g->digest());
                    return 0;
                 }

        Method add

          ``this_program` add(`string` `path`, `void`|`string` `base`)`

        Description

          Add a file, or a directory tree to the torrent. This will call add_directory_tree or add_file.

        Method add_announce

          ``this_program` add_announce(`string`|`array`(`string`) `announce_url`)`

        Description

          Add one or multiple announcers (trackers). This is needed to get a valid .torrent file. If this is called more then once, more announcers (trackers) will be added with lower priority.

        Method add_directory_tree

          ``this_program` add_directory_tree(`string` `path`, `void`|`string` `dirbase`)`

        Description

          Add a directory tree to the torrent. The second argument is what the directory will be called in the torrent. This will call add_file on all non-directories in the tree.

        Method add_file

          ``this_program` add_file(`string` `path`, `void`|`string` `filename`)`

        Description

          Add a file to the torrent. The second argument is what the file will be called in the torrent.

        Method build_sha1s

          ``void` build_sha1s(`void`|`function`(`int`, `int`:`void`) `progress_callback`)`

        Description

          Build the SHA hashes from the files.

        Method create

          `Protocols.Bittorrent.Generator Protocols.Bittorrent.Generator(`void`|`string` `base`, `void`|`int` `piece_size`)`

        Description

          Create a generator.

        Parameter `base`

          The base filename/path in the torrent.

        Parameter `piece_size`

          The size of the pieces that the SHA hashes are calculated on. Default 262144 and this value should probably be 2^n.

        Method digest

          ``string` digest(`void`|`function`(`int`, `int`:`void`) `progress_callback`)`

        Description

          Finally make a torrent string out of this information. Will call build_sha1's if the sha1's aren't generated already.

          `progress_callback` is called with (pos,of) arguments, similar to `Torrent.verify_targets`.

        Inherit Torrent

          `inherit .Torrent : Torrent`

      ## Class Protocols.Bittorrent.Peer

        Method connect

          ``void` connect()`

        Description

          Connect to the peer; this is done async. status/mode will change from `"connecting"` to `"dead"` or to `"connected"` depending on result. Will throw error if already online.

          Upon connect, protocol will be initiated in choked mode. When the protocol is up, status will change to `"online"` (or `"failed"` if the handshake failed).

        Method disconnect

          ``void` disconnect()`

        Description

          Disconnect a peer. Does nothing if we aren't online. status/mode will change to `"disconnected"`,1 if we were online.

        Method downloading_pieces

          ``multiset`(`int`) downloading_pieces()`

        Description

          Returns as multiset what this peer is downloading.

        Method is_activated

          ``int` is_activated()`

        Description

          Returns true if this peer is activated, as in we're downloading from it.

        Method is_available

          ``int` is_available()`

        Description

          Returns true if this peer is available, as in we can use it to download stuff.

        Method is_choked

          ``int` is_choked()`

        Description

          Returns true if this peer is choking, as in doesn't send more data to us.

        Method is_completed

          ``int` is_completed()`

        Description

          Returns true if this peer is completed, as in has downloaded everything already - and we shouldn't need to upload to get stuff.

        Method is_connectable

          ``int` is_connectable()`

        Description

          Returns true if we can connect to this peer, when new or disconnected but not fatally.

        Method is_online

          ``int` is_online()`

        Description

          Returns true if this peer is online and connected.

        Method is_strangled

          ``int` is_strangled()`

        Description

          Returns true if this peer is strangled; as in we don't want to upload more, because we're not getting any back.

        Method request

          ``void` request(`int` `piece`, `int` `offset`, `int` `bytes`, `function`(`int`, `int`, `string`, `object`:`void`|`mixed`) `callback`)`

        Description

          Called to request a chunk from this peer.

        Method send_have

          ``void` send_have(`int` `n`)`

        Description

          Send a have message to tell I now have piece n. Ignored if not online.

        Method status

          ``void` status(`string` `type`, `void`|`int`|`string` `data`)`

        Description

          Called whenever there is a status change for this peer. Always called with `"created"` when the object is created.

          Does not need to call inherited function.

      ## Class Protocols.Bittorrent.Port

        Method create

          `Protocols.Bittorrent.Port Protocols.Bittorrent.Port(`.Torrent` `_parent`)`

        Description

          Bind a port for this Torrent.

      ## Class Protocols.Bittorrent.Torrent

        Description

          Bittorrent peer - download and share. Read more about bittorrent at http://bitconjurer.org/BitTorrent/introduction.html

        Example

              The smallest usable torrent downloader. As first argument,
               it expects a filename to a .torrent file.
              int main(int ac,array am)
                {
                   // initialize Torrent from file:
                   Protocols.Bittorrent.Torrent t=Protocols.Bittorrent.Torrent();
                   t->load_metainfo(am[1]);

                   // Callback when download status changes:
                   // t->downloads_update_status=...;

                   // Callback when pieces status change (when we get new stuff):
                   // t->pieces_update_status=...;

                   // Callback when peer status changes (connect, disconnect, choked...):
                   // t->peer_update_status=...;

                   // Callback when download is completed:
                   t->download_completed_callback=
                      lambda()
                      {
                          call_out(exit,3600,0);    // share for an hour, then exit
                      };

                   // Callback to print warnings (same args as sprintf):
                   //   t->warning=werror;

                   // type of progress function used below:
                   void progress(int n,int of) { /* ... */ };

                   // Initiate targets from Torrent,
                   // if target was created, no need to verify:
                   if (t->fix_targets(1,0,progress)==1)
                      t->verify_targets(progress);

                   // Open port to listen on,
                   // we want to do this to be able to talk to firewalled peers:
                   t->open_port(6881);

                   // Ok, start calling tracker to get peers,
                   // and tell about us:
                   t->start_update_tracker();

                   // Finally, start the download:
                   t->start_download();

                   return -1;
                }

        Method bytes_done

          ``int` bytes_done()`

        Description

          Calculate the bytes successfully downloaded (full pieces).

        Method bytes_left

          ``int` bytes_left()`

        Description

          Calculate the bytes left to download.

        Method contact_peers

          ``void` contact_peers(`void`|`int` `n`)`

        Description

          Contact all or n peers.

        Variable do_we_strangle

          ``function`(`.Peer`, `int`, `int`:`bool`) Protocols.Bittorrent.Torrent.do_we_strangle`

        Description

          Function to determine if we should strangle this peer. Default is to allow 100000 bytes of data over the ratio, which is 2:1 per default; upload twice as much as we get.

          Arguments are the peer, bytes in (downloaded) and bytes out (uploaded). Return 1 to strangle and 0 to allow the peer to proceed downloading again.

        Variable download_completed_callback

          ``function`(:`void`) Protocols.Bittorrent.Torrent.download_completed_callback`

        Description

          If set, called when download is completed.

        Variable downloads_update_status

          ``function`(:`void`) Protocols.Bittorrent.Torrent.downloads_update_status`

        Description

          If set, called when we start to download another piece (no args).

        Method file_got_bitfield

          ``string` file_got_bitfield()`

        Description

          Returns the file got field as a string bitfield (cached).

        Method fix_targets

          ``int` fix_targets(`void`|`int(-1..2)` `allocate`, `void`|`string` `base_filename`, `void`|`function`(`int`, `int`:`void`) `progress_callback`)`

        Description

          Opens target datafile(s).

          If all files are created, the verify info will be filled as well, but if it isn't created, a call to `verify_target()` is necessary after this call.

        Parameter `allocate`

          Determines allocation procedure if the file doesn't exist:

          ``0`` | Don't allocate.
          ``1`` | Allocate virtual file size (seek, write end byte).
          ``2`` | Allocate for real (will call progress_callback(pos,length)).
          ``-1`` | Means never create a file, only open old files.

        Parameter `my_filename`

          A new base filename to substitute the metainfo base target filename with.

        Returns

          ``1`` | The (a) file was already there.
          ``2`` | All target files were created.

        Method load_metainfo

          ``void` load_metainfo(`string` `filename`)`

        Description

          Loads the metainfo from a file.

        Method open_port

          ``void` open_port(`void`|`int` `port`)`

        Description

          Open the port we're listening on.

        Variable peer_update_status

          ``function`(:`void`) Protocols.Bittorrent.Torrent.peer_update_status`

        Description

          If set, called when peer status changes.

        Variable pieces_update_status

          ``function`(:`void`) Protocols.Bittorrent.Torrent.pieces_update_status`

        Description

          If set, called when we got another piece downloaded (no args).

        Method start_download

          ``void` start_download()`

        Description

          Initiate the downloading scheme.

        Method start_update_tracker

          ``void` start_update_tracker(`void`|`int` `interval`)`

        Description

          Starts to contact the tracker at regular intervals, giving it the status and recieving more peers to talk to. Will also contact these peers. The default interval is 5 minutes. If given an event, will update tracker with it.

        Method stop_update_tracker

          ``void` stop_update_tracker(`void`|`string` `event`)`

        Description

          Stops updating the tracker; will send the event as a last event, if set. It will not contact new peers.

        Method update_tracker

          ``void` update_tracker(`void`|`string` `event`, `void`|`int` `contact`)`

        Description

          Contact and update the tracker with current status will fill the peer list.

        Method verify_targets

          ``void` verify_targets(`void`|`function`(`int`, `int`:`void`) `progress_callback`)`

        Description

          Verify the file and fill file_got (necessary after load_info, but needs open_file before this call). [ progress_callback(at chunk,total chunks) ]

        Variable warning

          ``function`(`string`, `mixed` ... :`void`|`mixed`) Protocols.Bittorrent.Torrent.warning`

        Description

          Called if there is a protocol error.

        ## Class Protocols.Bittorrent.Torrent.Target

          Description

            Each bittorrent has one or more target files. This represents one of those.

          Variable base
          Variable length
          Variable offset
          Variable path

            ``string` Protocols.Bittorrent.Torrent.Target.base`
            ``int` Protocols.Bittorrent.Torrent.Target.length`
            ``int` Protocols.Bittorrent.Torrent.Target.offset`
            ``void`|`array` Protocols.Bittorrent.Torrent.Target.path`

          Method create

            `Protocols.Bittorrent.Torrent.Target Protocols.Bittorrent.Torrent.Target(`string` `base`, `int` `length`, `int` `offset`, `void`|`array` `path`)`

      ## Class Protocols.Bittorrent.Tracker

        Method add_torrent

          ``void` add_torrent(`string` `id`)`

        Description

          Add a torrent to the tracker.

        Parameter `id`

          The info hash of the torrent file.

        Method announce

          ``string` announce(`mapping` `args`, `string` `ip`)`

        Description

          Handles HTTP announce queries to the tracker.

        Variable dynamic_add_torrents

          ``bool` Protocols.Bittorrent.Tracker.dynamic_add_torrents`

        Description

          Allow clients to dynamically add torrents to the tracker.

        Variable interval

          ``int(0..)` Protocols.Bittorrent.Tracker.interval`

        Description

          The query interval reported back to clients. Defaults to `1800`.

        Method scrape

          ``string` scrape(`mapping` `args`)`

        Description

          Returns the result of a scrape query.

      ## Module Protocols.Bittorrent.Bencoding

        Method _decode

          ``array`(`string`|`int`|`array`|`mapping`) _decode(`string` `what`)`

        Description

          Decodes a Bittorrent bencoded data chunk.

        Returns

          Array
          ``string`|`int`|`array`|`mapping` `data`` | The decoded data. UNDEFINED if no data could be decoded.
          ``string` `remainder`` | The trailing data that wasn't decoded.

        Method bits2string

          ``string` bits2string(`array`(`bool`) `v`)`

        Description

          Convert an array of `int(0..1)` to a Bittorrent style bitstring. Input will be padded to even bytes.

        Method decode

          ``string`|`int`|`array`|`mapping` decode(`string` `what`)`

        Description

          Decodes a Bittorrent bencoded data chunk and ignores the remaining string. Returns UNDEFINED if the data is incomplete.

        Method encode

          ``string` encode(`string`|`int`|`array`|`mapping` `data`)`

        Description

          Encodes a Bittorrent bencoded data chunk.

        Method string2arr

          ``array`(`int`) string2arr(`string` `s`)`

        Description

          Convert a Bittorrent style bitstring to an array of indices.

        Method string2bits

          ``array`(`bool`) string2bits(`string` `s`)`

        Description

          Convert a Bittorrent style bitstring to an array of `int(0..1)`.

      ## Module Protocols.Bittorrent.PeerID

        Method identify_peer

          ``string` identify_peer(`string` `peerid`)`

        Description

          Decodes the given `peerid`, returning an identification string for the client software. Assumes the `peerid` string is exactly 20 characters long.

    ## Module Protocols.DNS_SD

      ## Class Protocols.DNS_SD.Service

        Description

          This class provides an interface to DNS Service Discovery. The functionality of DNS-SD is described at <http://www.dns-sd.org/>.

          Using the Proctocols.DNS_SD.Service class a Pike program can announce services, for example a web site or a database server, to computers on the local network.

          When registering a service you need to provide the service name. service type, domain and port number. You can also optionally specify a TXT record. The contents of the TXT record varies between different services; for example, a web server can announce a path to a web page, and a printer spooler is able to list printer features such as color support or two-sided printing.

          The service is registered on the network for as long as the instance of the Service class is valid.

        Method create

          `Protocols.DNS_SD.Service Protocols.DNS_SD.Service(`string` `name`, `string` `service`, `string` `domain`, `int` `port`, `void`|`string`|`array`(`string`) `txt`)`

        Description

          Registers a service on the local network.

        Parameter `name`

          User-presentable name of the service.

        Parameter `service`

          Type of service on the form `_type._protocol`. Type is an identifier related to the service type. A list of registered service types can be found at http://http://www.dns-sd.org/ServiceTypes.html/. Protocol is normally `tcp` but `udp` is also a valid choice. For example, a web server would get a `service` of `_http._tcp`.

        Parameter `domain`

          Domain name. Normally an empty string which the DNS-SD library will translate into `local.`.

        Parameter `port`

          Port number for the service (e.g. 80 for a web site).

        Parameter `txt`

          An optional TXT record with service-specific information. It can be given as a plain string or an array of property assignment strings. The TXT record can be changed later by calling `update_txt` in the object returned when you register the service.

        Example

              object svc = Protocols.DNS_SD.Service(
                               "Company Intranet Forum",  //  name
                               "_http._tcp",              //  service type
                               "",                        //  domain (default)
                               80,                        //  port
                               ({ "path=/forum/" })       //  TXT record
                             );

        Inherit Service

          `inherit _Protocols_DNS_SD.Service : Service`

        Method update_txt

          ``void` update_txt(`string`|`array`(`string`) `txt`)`

        Description

          Updates the TXT record for the service.

        Parameter `txt`

          A TXT record with service-specific information. It can be given as a plain string or an array of property assignment strings. To remove an existing TXT record you give an empty string as the argument.

    ## Module Protocols.IPv6

      Method format_addr_short

        ``string` format_addr_short(`array`(`int(16bit)`) `bin_addr`)`

      Description

        Formats an IPv6 address to the colon-separated hexadecimal form as defined in RFC 2373, section 2.2. `bin_addr` must be an 8-element array containing the 16-bit fields.

        The returned address is on a canonical shortest form as follows: The longest sequence of zeroes is shortened using `"::"`. If there are several of equal length then the leftmost is shortened. All hexadecimal letters are lower-case. There are no superfluous leading zeroes in the fields.

      See also

        `parse_addr`

      Method normalize_addr_basic

        ``string` normalize_addr_basic(`string` `addr`)`

      Description

        Normalizes a formatted IPv6 address to a string with eight hexadecimal numbers separated by `":"`. `addr` is given on the same form, or any of the shorthand varieties as specified in RFC 2373, section 2.2.

        All hexadecimal letters in the returned address are lower-case, and there are no superfluous leading zeroes in the fields.

        Zero is returned if `addr` is incorrectly formatted.

      See also

        `normalize_addr_short`

      Method normalize_addr_short

        ``string` normalize_addr_short(`string` `addr`)`

      Description

        Normalizes a formatted IPv6 address to a canonical shortest form. `addr` is parsed according to the hexadecimal `"x:x:x:x:x:x:x:x"` syntax or any of its shorthand varieties (see RFC 2373, section 2.2).

        The returned address is normalized as follows: The longest sequence of zeroes is shortened using `"::"`. If there are several of equal length then the leftmost is shortened. All hexadecimal letters are lower-case. There are no superfluous leading zeroes in the fields.

        Zero is returned if `addr` is incorrectly formatted.

      See also

        `normalize_addr_basic`

      Method parse_addr

        ``array`(`int(16bit)`) parse_addr(`string` `addr`)`

      Description

        Parses an IPv6 address on the formatted hexadecimal `"x:x:x:x:x:x:x:x"` form, or any of the shorthand varieties (see RFC 2373, section 2.2).

        The address is returned as an 8-element array where each element is the value of the corresponding field. Zero is returned if `addr` is incorrectly formatted.

      See also

        `format_addr_short`

    ## Module Protocols.IRC

      ## Class Protocols.IRC.Channel

        Description

          Abstract class for a IRC channel.

        Variable name

          ``string` Protocols.IRC.Channel.name`

        Description

          The name of the channel.

      ## Class Protocols.IRC.Client

        Method close

          ``void` close()`

        Description

          Closes the connection to the server.

        Method create

          `Protocols.IRC.Client Protocols.IRC.Client(`string`|`object` `server`, `void`|`mapping`(`string`:`mixed`) `options`)`

        Parameter `server`

          The IRC server to connect to. If server is an object, it is assumed to be a newly established connection to the IRC server to be used. Pass `SSL.File` connections here to connect to SSL secured IRC networks.

        Parameter `options`

          An optional mapping with additional IRC client options.

          ``"port"` : `int`` | Defaults to 6667.
          ``"user"` : `string`` | Defaults to `"unknown"` on systems without `getpwuid` and `getuid` and to `getpwuid(getuid())[0]` on systems with.
          ``"nick"` : `string`` | Defaults to `"Unknown"` on systems without `getpwuid` and `getuid` and to `String.capitalize(getpwuid(getuid())[0])` on systems with.
          ``"pass"` : `string`` | Server password, if any. Public servers seldom require this.
          ``"realname"` : `string`` | Defaults to `"Mr. Anonymous"` on systems without `getpwuid` and `getuid` and to `getpwuid(getuid())[4]` on systems with.
          ``"host"` : `string`` | Defaults to `"localhost"` on systems without `uname` and to `uname()->nodename` on systems with.
          ``"ping_interval"` : `int`` | Defaults to 120.
          ``"ping_timeout"` : `int`` | Defaults to 120.
          ``"connection_lost"` : `function`(`void`:`void`)` | This function is called when the connection to the IRC server is lost or when a ping isn't answered with a pong within the time set by the `ping_timeout` option. The default behaviour is to complain on stderr and self destruct.
          ``"error_notify"` : `function`(`mixed` ... :`void`)` | This function is called when a KILL or ERROR command is recieved from the IRC server.
          ``"system_notify"` : `function`(`string`, `void`|`string`:`void`)` |
          ``"motd_notify"` : `function`(`string`, `void`|`string`:`void`)` |
          ``"error_nickinuse"` : `function`(`string`:`void`)` |
          ``"generic_notify"` : `function`(`string`, `string`, `string`, `string`, `string`:`void`)` | The arguments are from, type, to, message and extra.
          ``"quit_notify"` : `function`(`string`, `string`:`void`)` | The arguments are who and why.
          ``"privmsg_notify"` : `function`(`Person`, `string`, `string`:`void`)` | The arguments are originator, message and to.
          ``"notice_notify"` : `function`(`Person`, `string`, `string`:`void`)` | The arguments are originator, message and to.
          ``"nick_notify"` : `function`(`Person`, `string`:`void`)` | The arguments are originator and to.

      ## Class Protocols.IRC.Person

        Description

          Abstract class for a person.

        Variable ip

          ``string` Protocols.IRC.Person.ip`

        Description

          User domain, e.g. `"mistel.idonex.se"`.

        Variable last_action

          ``int` Protocols.IRC.Person.last_action`

        Description

          Time of last action, represented as posix time.

        Variable nick

          ``string` Protocols.IRC.Person.nick`

        Description

          User nickname, e.g. `"Mirar"`.

        Variable user

          ``string` Protocols.IRC.Person.user`

        Description

          User name, e.g. `"mirar"`.

    ## Module Protocols.Ident

      Description

        An implementation of the IDENT protocol, specified in RFC 931.

      Method lookup

        ``array`(`string`) lookup(`object` `fd`)`

      Throws

        Throws exception upon any error.

      ## Class Protocols.Ident.AsyncLookup

        Method create

          `Protocols.Ident.AsyncLookup Protocols.Ident.AsyncLookup(`object` `fd`, `function`(`array`(`string`), `mixed` ... :`void`) `cb`, `mixed` ... `args`)`

    ## Module Protocols.LDAP

      Constant GUID_USERS_CONTAINER
      Constant GUID_COMPUTERS_CONTAINER
      Constant GUID_SYSTEMS_CONTAINER
      Constant GUID_DOMAIN_CONTROLLERS_CONTAINER
      Constant GUID_INFRASTRUCTURE_CONTAINER
      Constant GUID_DELETED_OBJECTS_CONTAINER
      Constant GUID_LOSTANDFOUND_CONTAINER
      Constant GUID_FOREIGNSECURITYPRINCIPALS_CONTAINER
      Constant GUID_PROGRAM_DATA_CONTAINER
      Constant GUID_MICROSOFT_PROGRAM_DATA_CONTAINER
      Constant GUID_NTDS_QUOTAS_CONTAINER

        ``constant` `string` Protocols.LDAP.`GUID_USERS_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_COMPUTERS_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_SYSTEMS_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_DOMAIN_CONTROLLERS_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_INFRASTRUCTURE_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_DELETED_OBJECTS_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_LOSTANDFOUND_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_FOREIGNSECURITYPRINCIPALS_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_PROGRAM_DATA_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_MICROSOFT_PROGRAM_DATA_CONTAINER``
        ``constant` `string` Protocols.LDAP.`GUID_NTDS_QUOTAS_CONTAINER``

      Description

        Constants for Microsoft AD Well-Known Object GUIDs. These are e.g. used in LDAP URLs:

            "ldap://server/<WKGUID=" + Protocols.LDAP.GUID_USERS_CONTAINER +
              ",dc=my,dc=domain,dc=com>"

      Constant LDAP_SUCCESS
      Constant LDAP_OPERATIONS_ERROR
      Constant LDAP_PROTOCOL_ERROR
      Constant LDAP_TIMELIMIT_EXCEEDED
      Constant LDAP_SIZELIMIT_EXCEEDED
      Constant LDAP_COMPARE_FALSE
      Constant LDAP_COMPARE_TRUE
      Constant LDAP_AUTH_METHOD_NOT_SUPPORTED
      Constant LDAP_STRONG_AUTH_NOT_SUPPORTED
      Constant LDAP_STRONG_AUTH_REQUIRED
      Constant LDAP_PARTIAL_RESULTS
      Constant LDAP_REFERRAL
      Constant LDAP_ADMINLIMIT_EXCEEDED
      Constant LDAP_UNAVAILABLE_CRITICAL_EXTENSION
      Constant LDAP_CONFIDENTIALITY_REQUIRED
      Constant LDAP_SASL_BIND_IN_PROGRESS
      Constant LDAP_NO_SUCH_ATTRIBUTE
      Constant LDAP_UNDEFINED_TYPE
      Constant LDAP_INAPPROPRIATE_MATCHING
      Constant LDAP_CONSTRAINT_VIOLATION
      Constant LDAP_TYPE_OR_VALUE_EXISTS
      Constant LDAP_INVALID_SYNTAX
      Constant LDAP_NO_SUCH_OBJECT
      Constant LDAP_ALIAS_PROBLEM
      Constant LDAP_INVALID_DN_SYNTAX
      Constant LDAP_IS_LEAF
      Constant LDAP_ALIAS_DEREF_PROBLEM
      Constant LDAP_INAPPROPRIATE_AUTH
      Constant LDAP_INVALID_CREDENTIALS
      Constant LDAP_INSUFFICIENT_ACCESS
      Constant LDAP_BUSY
      Constant LDAP_UNAVAILABLE
      Constant LDAP_UNWILLING_TO_PERFORM
      Constant LDAP_LOOP_DETECT
      Constant LDAP_SORT_CONTROL_MISSING
      Constant LDAP_NAMING_VIOLATION
      Constant LDAP_OBJECT_CLASS_VIOLATION
      Constant LDAP_NOT_ALLOWED_ON_NONLEAF
      Constant LDAP_NOT_ALLOWED_ON_RDN
      Constant LDAP_ALREADY_EXISTS
      Constant LDAP_NO_OBJECT_CLASS_MODS
      Constant LDAP_RESULTS_TOO_LARGE
      Constant LDAP_AFFECTS_MULTIPLE_DSAS
      Constant LDAP_OTHER

        ``constant` `int` Protocols.LDAP.`LDAP_SUCCESS``
        ``constant` `int` Protocols.LDAP.`LDAP_OPERATIONS_ERROR``
        ``constant` `int` Protocols.LDAP.`LDAP_PROTOCOL_ERROR``
        ``constant` `int` Protocols.LDAP.`LDAP_TIMELIMIT_EXCEEDED``
        ``constant` `int` Protocols.LDAP.`LDAP_SIZELIMIT_EXCEEDED``
        ``constant` `int` Protocols.LDAP.`LDAP_COMPARE_FALSE``
        ``constant` `int` Protocols.LDAP.`LDAP_COMPARE_TRUE``
        ``constant` `int` Protocols.LDAP.`LDAP_AUTH_METHOD_NOT_SUPPORTED``
        ``constant` Protocols.LDAP.`LDAP_STRONG_AUTH_NOT_SUPPORTED``
        ``constant` `int` Protocols.LDAP.`LDAP_STRONG_AUTH_REQUIRED``
        ``constant` `int` Protocols.LDAP.`LDAP_PARTIAL_RESULTS``
        ``constant` `int` Protocols.LDAP.`LDAP_REFERRAL``
        ``constant` `int` Protocols.LDAP.`LDAP_ADMINLIMIT_EXCEEDED``
        ``constant` `int` Protocols.LDAP.`LDAP_UNAVAILABLE_CRITICAL_EXTENSION``
        ``constant` `int` Protocols.LDAP.`LDAP_CONFIDENTIALITY_REQUIRED``
        ``constant` `int` Protocols.LDAP.`LDAP_SASL_BIND_IN_PROGRESS``
        ``constant` `int` Protocols.LDAP.`LDAP_NO_SUCH_ATTRIBUTE``
        ``constant` `int` Protocols.LDAP.`LDAP_UNDEFINED_TYPE``
        ``constant` `int` Protocols.LDAP.`LDAP_INAPPROPRIATE_MATCHING``
        ``constant` `int` Protocols.LDAP.`LDAP_CONSTRAINT_VIOLATION``
        ``constant` `int` Protocols.LDAP.`LDAP_TYPE_OR_VALUE_EXISTS``
        ``constant` `int` Protocols.LDAP.`LDAP_INVALID_SYNTAX``
        ``constant` `int` Protocols.LDAP.`LDAP_NO_SUCH_OBJECT``
        ``constant` `int` Protocols.LDAP.`LDAP_ALIAS_PROBLEM``
        ``constant` `int` Protocols.LDAP.`LDAP_INVALID_DN_SYNTAX``
        ``constant` `int` Protocols.LDAP.`LDAP_IS_LEAF``
        ``constant` `int` Protocols.LDAP.`LDAP_ALIAS_DEREF_PROBLEM``
        ``constant` `int` Protocols.LDAP.`LDAP_INAPPROPRIATE_AUTH``
        ``constant` `int` Protocols.LDAP.`LDAP_INVALID_CREDENTIALS``
        ``constant` `int` Protocols.LDAP.`LDAP_INSUFFICIENT_ACCESS``
        ``constant` `int` Protocols.LDAP.`LDAP_BUSY``
        ``constant` `int` Protocols.LDAP.`LDAP_UNAVAILABLE``
        ``constant` `int` Protocols.LDAP.`LDAP_UNWILLING_TO_PERFORM``
        ``constant` `int` Protocols.LDAP.`LDAP_LOOP_DETECT``
        ``constant` `int` Protocols.LDAP.`LDAP_SORT_CONTROL_MISSING``
        ``constant` `int` Protocols.LDAP.`LDAP_NAMING_VIOLATION``
        ``constant` `int` Protocols.LDAP.`LDAP_OBJECT_CLASS_VIOLATION``
        ``constant` `int` Protocols.LDAP.`LDAP_NOT_ALLOWED_ON_NONLEAF``
        ``constant` `int` Protocols.LDAP.`LDAP_NOT_ALLOWED_ON_RDN``
        ``constant` `int` Protocols.LDAP.`LDAP_ALREADY_EXISTS``
        ``constant` `int` Protocols.LDAP.`LDAP_NO_OBJECT_CLASS_MODS``
        ``constant` `int` Protocols.LDAP.`LDAP_RESULTS_TOO_LARGE``
        ``constant` `int` Protocols.LDAP.`LDAP_AFFECTS_MULTIPLE_DSAS``
        ``constant` `int` Protocols.LDAP.`LDAP_OTHER``

      Description

        LDAP result codes.

      See also

        `Protocols.LDAP.client.error_number`, `Protocols.LDAP.client.result.error_number`

      Constant LDAP_CONTROL_MANAGE_DSA_IT

        ``constant` `string` Protocols.LDAP.`LDAP_CONTROL_MANAGE_DSA_IT``

      Description

        LDAP control: Manage DSA IT LDAPv3 control (RFC 3296): Control to indicate that the operation is intended to manage objects within the DSA (server) Information Tree.

      Constant LDAP_CONTROL_VLVREQUEST

        ``constant` `string` Protocols.LDAP.`LDAP_CONTROL_VLVREQUEST``

      Description

        LDAP control: LDAP Extensions for Scrolling View Browsing of Search Results (internet draft): Control used to request virtual list view support from the server.

      Constant LDAP_CONTROL_VLVRESPONSE

        ``constant` `string` Protocols.LDAP.`LDAP_CONTROL_VLVRESPONSE``

      Description

        LDAP control: LDAP Extensions for Scrolling View Browsing of Search Results (internet draft): Control used to pass virtual list view (VLV) data from the server to the client.

      Constant LDAP_PAGED_RESULT_OID_STRING

        ``constant` `string` Protocols.LDAP.`LDAP_PAGED_RESULT_OID_STRING``

      Description

        LDAP control: Microsoft AD: Control to instruct the server to return the results of a search request in smaller, more manageable packets rather than in one large block.

      Constant LDAP_SERVER_ASQ_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_ASQ_OID``

      Description

        LDAP control: Microsoft AD: Control to force the query to be based on a specific DN-valued attribute.

      Constant LDAP_SERVER_CROSSDOM_MOVE_TARGET_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_CROSSDOM_MOVE_TARGET_OID``

      Description

        LDAP control: Microsoft AD: Control used with an extended LDAP rename function to move an LDAP object from one domain to another.

      Constant LDAP_SERVER_DIRSYNC_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_DIRSYNC_OID``

      Description

        LDAP control: Microsoft AD: Control that enables an application to search the directory for objects changed from a previous state.

      Constant LDAP_SERVER_DOMAIN_SCOPE_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_DOMAIN_SCOPE_OID``

      Description

        LDAP control: Microsoft AD: Control used to instruct the LDAP server not to generate any referrals when completing a request.

      Constant LDAP_SERVER_EXTENDED_DN_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_EXTENDED_DN_OID``

      Description

        LDAP control: Microsoft AD: Control to request an extended form of an Active Directory object distinguished name.

      Constant LDAP_SERVER_LAZY_COMMIT_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_LAZY_COMMIT_OID``

      Description

        LDAP control: Microsoft AD: Control used to instruct the server to return the results of a DS modification command, such as add, delete, or replace, after it has been completed in memory, but before it has been committed to disk.

      Constant LDAP_SERVER_NOTIFICATION_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_NOTIFICATION_OID``

      Description

        LDAP control: Microsoft AD: Control used with an extended LDAP asynchronous search function to register the client to be notified when changes are made to an object in Active Directory.

      Constant LDAP_SERVER_PERMISSIVE_MODIFY_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_PERMISSIVE_MODIFY_OID``

      Description

        LDAP control: Microsoft AD: An LDAP modify request will normally fail if it attempts to add an attribute that already exists, or if it attempts to delete an attribute that does not exist. With this control, as long as the attribute to be added has the same value as the existing attribute, then the modify will succeed. With this control, deletion of an attribute that does not exist will also succeed.

      Constant LDAP_SERVER_QUOTA_CONTROL_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_QUOTA_CONTROL_OID``

      Description

        LDAP control: Microsoft AD: Control used to pass the SID of a security principal, whose quota is being queried, to the server in a LDAP search operation.

      Constant LDAP_SERVER_RESP_SORT_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_RESP_SORT_OID``

      Description

        LDAP control: Microsoft AD: Control used by the server to indicate the results of a search function initiated using the `LDAP_SERVER_SORT_OID` control.

      Constant LDAP_SERVER_SD_FLAGS_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_SD_FLAGS_OID``

      Description

        LDAP control: Microsoft AD: Control used to pass flags to the server to control various security descriptor results.

      Constant LDAP_SERVER_SEARCH_OPTIONS_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_SEARCH_OPTIONS_OID``

      Description

        LDAP control: Microsoft AD: Control used to pass flags to the server to control various search behaviors.

      Constant LDAP_SERVER_SHOW_DELETED_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_SHOW_DELETED_OID``

      Description

        LDAP control: Microsoft AD: Control used to specify that the search results include any deleted objects that match the search filter.

      Constant LDAP_SERVER_SORT_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_SORT_OID``

      Description

        LDAP control: Microsoft AD: Control used to instruct the server to sort the search results before returning them to the client application.

      Constant LDAP_SERVER_TREE_DELETE_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_TREE_DELETE_OID``

      Description

        LDAP control: Microsoft AD: Control used to delete an entire subtree in the directory.

      Constant LDAP_SERVER_VERIFY_NAME_OID

        ``constant` `string` Protocols.LDAP.`LDAP_SERVER_VERIFY_NAME_OID``

      Description

        LDAP control: Microsoft AD: Control used to instruct the DC accepting the update which DC it should verify with, the existence of any DN attribute values.

      Constant MODIFY_ADD
      Constant MODIFY_DELETE
      Constant MODIFY_REPLACE

        ``constant` `int` Protocols.LDAP.`MODIFY_ADD``
        ``constant` `int` Protocols.LDAP.`MODIFY_DELETE``
        ``constant` `int` Protocols.LDAP.`MODIFY_REPLACE``

      Description

        Constants used in the `attropval` argument to `Protocols.LDAP.client.modify`.

      Constant SCOPE_BASE
      Constant SCOPE_ONE
      Constant SCOPE_SUB

        ``constant` `int` Protocols.LDAP.`SCOPE_BASE``
        ``constant` `int` Protocols.LDAP.`SCOPE_ONE``
        ``constant` `int` Protocols.LDAP.`SCOPE_SUB``

      Description

        Constants for the search scope used with e.g. `Protocols.LDAP.client.set_scope`.

        SCOPE_BASE

          Return the object specified by the DN.

        SCOPE_ONE

          Return the immediate subobjects of the object specified by the DN.

        SCOPE_SUB

          Return the object specified by the DN and all objects below it (on any level).

      Constant SEARCH_LOWER_ATTRS
      Constant SEARCH_MULTIVAL_ARRAYS_ONLY
      Constant SEARCH_RETURN_DECODE_ERRORS

        ``constant` `int` Protocols.LDAP.`SEARCH_LOWER_ATTRS``
        ``constant` `int` Protocols.LDAP.`SEARCH_MULTIVAL_ARRAYS_ONLY``
        ``constant` `int` Protocols.LDAP.`SEARCH_RETURN_DECODE_ERRORS``

      Description

        Bitfield flags given to `Protocols.LDAP.client.search`:

        SEARCH_LOWER_ATTRS

          Lowercase all attribute values. This makes it easier to match specific attributes in the mappings returned by `Protocols.LDAP.client.result.fetch` since LDAP attribute names are case insensitive.

        SEARCH_MULTIVAL_ARRAYS_ONLY

          Only use arrays for attribute values where the attribute syntax specify multiple values. I.e. the values for single valued attributes are returned as strings instead of arrays containing one string element.

          If no value is returned for a single valued attribute, e.g. when `attrsonly` is set in the search call, then a zero will be used as value.

          The special `"dn"` value is also returned as a string when this flag is set.

          Note that it's the attribute type descriptions that are used to decide this, not the number of values a particular attribute happens to have in the search result.

        SEARCH_RETURN_DECODE_ERRORS

          Don't throw attribute value decode errors, instead return them in the result from `Protocols.LDAP.client.result.fetch` in place of the value. I.e. anywhere an attribute value string occurs, you might instead have a `Charset.DecodeError` object.

      Constant SYNTAX_AD_CASE_IGNORE_STR
      Constant SYNTAX_AD_LARGE_INT
      Constant SYNTAX_AD_OBJECT_SECURITY_DESCRIPTOR

        ``constant` `string` Protocols.LDAP.`SYNTAX_AD_CASE_IGNORE_STR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_AD_LARGE_INT``
        ``constant` `string` Protocols.LDAP.`SYNTAX_AD_OBJECT_SECURITY_DESCRIPTOR``

      Description

        LDAP syntax: Microsoft AD: Additional syntaxes used in AD. C.f. <http://community.roxen.com/(all)/developers/idocs/drafts/ draft-armijo-ldap-syntax-00.html>.

      Constant SYNTAX_ATTR_TYPE_DESCR
      Constant SYNTAX_BINARY
      Constant SYNTAX_BIT_STRING
      Constant SYNTAX_BOOLEAN
      Constant SYNTAX_CERT
      Constant SYNTAX_CERT_LIST
      Constant SYNTAX_CERT_PAIR
      Constant SYNTAX_COUNTRY_STR
      Constant SYNTAX_DN
      Constant SYNTAX_DIRECTORY_STR
      Constant SYNTAX_DIT_CONTENT_RULE_DESCR
      Constant SYNTAX_FACSIMILE_PHONE_NUM
      Constant SYNTAX_FAX
      Constant SYNTAX_GENERALIZED_TIME
      Constant SYNTAX_IA5_STR
      Constant SYNTAX_INT
      Constant SYNTAX_JPEG
      Constant SYNTAX_MATCHING_RULE_DESCR
      Constant SYNTAX_MATCHING_RULE_USE_DESCR
      Constant SYNTAX_MHS_OR_ADDR
      Constant SYNTAX_NAME_AND_OPTIONAL_UID
      Constant SYNTAX_NAME_FORM_DESCR
      Constant SYNTAX_NUMERIC_STRING
      Constant SYNTAX_OBJECT_CLASS_DESCR
      Constant SYNTAX_OID
      Constant SYNTAX_OTHER_MAILBOX
      Constant SYNTAX_POSTAL_ADDR
      Constant SYNTAX_PRESENTATION_ADDR
      Constant SYNTAX_PRINTABLE_STR
      Constant SYNTAX_PHONE_NUM
      Constant SYNTAX_UTC_TIME
      Constant SYNTAX_LDAP_SYNTAX_DESCR
      Constant SYNTAX_DIT_STRUCTURE_RULE_DESCR

        ``constant` `string` Protocols.LDAP.`SYNTAX_ATTR_TYPE_DESCR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_BINARY``
        ``constant` `string` Protocols.LDAP.`SYNTAX_BIT_STRING``
        ``constant` `string` Protocols.LDAP.`SYNTAX_BOOLEAN``
        ``constant` `string` Protocols.LDAP.`SYNTAX_CERT``
        ``constant` `string` Protocols.LDAP.`SYNTAX_CERT_LIST``
        ``constant` `string` Protocols.LDAP.`SYNTAX_CERT_PAIR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_COUNTRY_STR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_DN``
        ``constant` `string` Protocols.LDAP.`SYNTAX_DIRECTORY_STR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_DIT_CONTENT_RULE_DESCR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_FACSIMILE_PHONE_NUM``
        ``constant` `string` Protocols.LDAP.`SYNTAX_FAX``
        ``constant` `string` Protocols.LDAP.`SYNTAX_GENERALIZED_TIME``
        ``constant` `string` Protocols.LDAP.`SYNTAX_IA5_STR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_INT``
        ``constant` `string` Protocols.LDAP.`SYNTAX_JPEG``
        ``constant` `string` Protocols.LDAP.`SYNTAX_MATCHING_RULE_DESCR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_MATCHING_RULE_USE_DESCR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_MHS_OR_ADDR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_NAME_AND_OPTIONAL_UID``
        ``constant` `string` Protocols.LDAP.`SYNTAX_NAME_FORM_DESCR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_NUMERIC_STRING``
        ``constant` `string` Protocols.LDAP.`SYNTAX_OBJECT_CLASS_DESCR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_OID``
        ``constant` `string` Protocols.LDAP.`SYNTAX_OTHER_MAILBOX``
        ``constant` `string` Protocols.LDAP.`SYNTAX_POSTAL_ADDR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_PRESENTATION_ADDR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_PRINTABLE_STR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_PHONE_NUM``
        ``constant` `string` Protocols.LDAP.`SYNTAX_UTC_TIME``
        ``constant` `string` Protocols.LDAP.`SYNTAX_LDAP_SYNTAX_DESCR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_DIT_STRUCTURE_RULE_DESCR``

      Description

        LDAP syntax: Standard syntaxes from RFC 2252.

      Constant SYNTAX_CASE_EXACT_STR

        ``constant` Protocols.LDAP.`SYNTAX_CASE_EXACT_STR``

      Description

        `"caseExactString"` is an alias used in e.g. RFC 2079.

      Constant SYNTAX_DELIVERY_METHOD
      Constant SYNTAX_ENHANCED_GUIDE
      Constant SYNTAX_GUIDE
      Constant SYNTAX_OCTET_STR
      Constant SYNTAX_TELETEX_TERMINAL_ID
      Constant SYNTAX_TELETEX_NUM
      Constant SYNTAX_SUPPORTED_ALGORITHM

        ``constant` `string` Protocols.LDAP.`SYNTAX_DELIVERY_METHOD``
        ``constant` `string` Protocols.LDAP.`SYNTAX_ENHANCED_GUIDE``
        ``constant` `string` Protocols.LDAP.`SYNTAX_GUIDE``
        ``constant` `string` Protocols.LDAP.`SYNTAX_OCTET_STR``
        ``constant` `string` Protocols.LDAP.`SYNTAX_TELETEX_TERMINAL_ID``
        ``constant` `string` Protocols.LDAP.`SYNTAX_TELETEX_NUM``
        ``constant` `string` Protocols.LDAP.`SYNTAX_SUPPORTED_ALGORITHM``

      Description

        LDAP syntax: Standard syntaxes from RFC 2256.

      Method canonicalize_dn

        ``string` canonicalize_dn(`string` `dn`, `void`|`int` `strict`)`

      Description

        Returns the given distinguished name on a canonical form, so it reliably can be used in comparisons for equality. This means removing surplus whitespace, lowercasing attributes, normalizing quoting in string attribute values, lowercasing the hex digits in binary attribute values, and sorting the RDN parts separated by "+".

        The returned string follows RFC 2253. The input string may use legacy LDAPv2 syntax and is treated according to section 4 in RFC 2253.

        If `strict` is set then errors will be thrown if the given DN is syntactically invalid. Otherwise the invalid parts remain untouched in the result.

      Note

        The result is not entirely canonical since no conversion is done from or to hexadecimal BER encodings of the attribute values. It's assumed that the input already has the suitable value encoding depending on the attribute type.

      Note

        No UTF-8 encoding or decoding is done. The function can be used on both encoded and decoded input strings, and the result will be likewise encoded or decoded.

      Method encode_dn_value

        ``string` encode_dn_value(`string` `str`)`

      Description

        Encode the given string for use as an attribute value in a distinguished name (on string form).

        The encoding is according to RFC 2253 section 2.4 with the exception that characters above `0x7F` aren't UTF-8 encoded. UTF-8 encoding can always be done afterwards on the complete DN, which also is done internally by the `Protocols.LDAP` functions when LDAPv3 is used.

      Method get_cached_filter

        ``object` get_cached_filter(`string` `filter`, `void`|`int` `ldap_version`)`

      Description

        Like `make_filter` but saves the generated objects for reuse. Useful for filters that reasonably will occur often. The cache is never garbage collected, however.

      Throws

        If there's a parse error in the filter then a `FilterError` is thrown as from `make_filter`.

      Method get_connection

        ``object` get_connection(`string` `ldap_url`, `void`|`string` `binddn`, `void`|`string` `password`, `void`|`int` `version`, `void`|`SSL.Context` `ctx`)`

      Description

        Returns a client connection to the specified LDAP URL. If a bind DN is specified (either through a `"bindname"` extension in `ldap_url` or, if there isn't one, through `binddn`) then the connection will be bound using that DN and the optional password. If no bind DN is given then any connection is returned, regardless of the bind DN it is using.

        `version` may be used to specify the required protocol version in the bind operation. If zero or left out, a bind attempt with the default version (currently `3`) is done with a fallback to `2` if that fails. Also, a cached connection for any version might be returned if `version` isn't specified.

        `ctx` may be specified to control SSL/TLS parameters to use with the `"ldaps"`-protocol. Note that changing this only affects new connections.

        As opposed to creating an `Protocols.LDAP.client` instance directly, this function can return an already established connection for the same URL, provided connections are given back using `return_connection` when they aren't used anymore.

        A client object with an error condition is returned if there's a bind error, e.g. invalid password.

      Method get_constant_name

        ``string` get_constant_name(`mixed` `val`)`

      Description

        If `val` matches any non-integer constant in this module, its name is returned.

      Method ldap_decode_string

        ``string` ldap_decode_string(`string` `str`)`

      Description

        Decodes all `\xx` escapes in `str`.

      See also

        `ldap_encode_string`

      Method ldap_encode_string

        ``string` ldap_encode_string(`string` `str`)`

      Description

        Quote characters in the given string as necessary for use as a string literal in filters and various composite LDAP attributes.

        The quoting is compliant with RFCs 2252 (section 4.3) and 2254 (section 4). All characters that can be special in those RFCs are quoted using the `\xx` syntax, but the set might be extended.

      See also

        `ldap_decode_string`, `Protocols.LDAP.client.search`

      Constant ldap_error_strings

        ``constant` Protocols.LDAP.`ldap_error_strings``

      Description

        Mapping from `LDAP_*` result codes to descriptive strings.

      Method make_filter

        ``object` make_filter(`string` `filter`, `void`|`int` `ldap_version`)`

      Description

        Parses an LDAP filter string into an ASN1 object tree that can be given to `Protocols.LDAP.search`.

        Using this function instead of giving the filter string directly to the search function has two advantages: This function provides better error reports for syntax errors, and the same object tree can be used repeatedly to avoid reparsing the filter string.

      Parameter `filter`

        The filter to parse, according to the syntax specified in RFC 2254. The syntax is extended a bit to allow and ignore whitespace everywhere except inside and next to the filter values.

      Parameter `ldap_version`

        LDAP protocol version to make the filter for. This controls what syntaxes are allowed depending on the protocol version. Also, if the protocol is `3` or later then full Unicode string literals are supported. The default is the latest supported version.

      Returns

        An ASN1 object tree representing the filter.

      Throws

        `FilterError` is thrown if there's a syntax error in the filter.

      Method num_connections

        ``int` num_connections(`string` `ldap_url`)`

      Description

        Returns the number of currently stored connections for the given LDAP URL.

      Method parse_ldap_url

        ``mapping`(`string`:`mixed`) parse_ldap_url(`string` `ldap_url`)`

      Description

        Parses an LDAP URL and returns its fields in a mapping.

      Returns

        The returned mapping contains these fields:

        ``scheme` : `string`` | The URL scheme, either `"ldap"` or `"ldaps"`.
        ``host` : `string`` | Self-explanatory.
        ``port` : `int``
        ``basedn` : `string``
        ``attributes` : `array`(`string`)` | Array containing the attributes. Undefined if none was specified.
        ``scope` : `int`` | The scope as one of the `SEARCH_*` constants. Undefined if none was specified.
        ``filter` : `string`` | The search filter. Undefined if none was specified.
        ``ext` : `mapping`(`string`:`string`|`int(1..1)`)` | The extensions. Undefined if none was specified. The mapping values are `1` for extensions without values. Critical extensions are checked and the leading `"!"` do not remain in the mapping indices.
        ``url` : `string`` | The original unparsed URL.

      See also

        `get_parsed_url`

      Method return_connection

        ``void` return_connection(`object` `conn`)`

      Description

        Use this to return a connection to the connection pool after you've finished using it. The connection is assumed to be working.

      Note

        Ensure that persistent connection settings such as the scope and the base DN are restored to the defaults

      Constant syntax_decode_fns

        ``constant` `mapping`(`string`:`function`(`string`:`string`)) Protocols.LDAP.`syntax_decode_fns``

      Description

        Mapping containing functions to decode charsets in syntaxes where that's necessary. If the syntax is complex in a way that makes the result ambiguous if decoded with a single charset transformation then it should typically not be decoded here.

        These decoders are used on all attribute values returned by `Protocols.LDAP.client.result` functions.

      Constant syntax_encode_fns

        ``constant` `mapping`(`string`:`function`(`string`:`string`)) Protocols.LDAP.`syntax_encode_fns``

      Description

        Mapping containing the reverse functions from `syntax_decode_fns`.

      ## Class Protocols.LDAP.FilterError

        Description

          Error object thrown by `make_filter` for parse errors.

        Constant is_ldap_filter_error

          ``constant` `int` Protocols.LDAP.FilterError.`is_ldap_filter_error``

        Description

          Recognition constant.

      ## Class Protocols.LDAP.client

        Description

          Contains the client implementation of the LDAP protocol. All of the version 2 protocol features are implemented but only the base parts of the version 3.

        Method add

          ``int` add(`string` `dn`, `mapping`(`string`:`array`(`string`)) `attrs`)`

        Description

          The Add Operation allows a client to request the addition of an entry into the directory

        Parameter `dn`

          The Distinguished Name of the entry to be added.

        Parameter `attrs`

          The mapping of attributes and their values that make up the content of the entry being added. Values that are sent UTF-8 encoded according the the attribute syntaxes are encoded automatically.

        Returns

          Returns `1` on success, `0` otherwise.

        Note

          The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

        Method bind

          ``int` bind()`
          ``int` bind(`string` `dn`, `string` `password`)`
          ``int` bind(`string` `dn`, `string` `password`, `int` `version`)`

        Description

          Authenticates connection to the direcory.

          First form uses default value previously entered in create.

          Second form uses value from parameters:

        Parameter `dn`

          The distinguished name (DN) of an entry aginst which will be made authentication.

        Parameter `password`

          Password used for authentication.

          Third form allows specify the version of LDAP protocol used by connection to the LDAP server.

        Parameter `version`

          The desired protocol version (current `2` or `3`). Defaults to `3` if zero or left out.

        Returns

          Returns `1` on success, `0` otherwise.

        Note

          Only simple authentication type is implemented. So be warned clear text passwords are sent to the directory server.

        Note

          The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

        Method compare

          ``int` compare(`string` `dn`, `string` `attr`, `string` `value`)`

        Description

          Compares an attribute value with one in the directory.

        Parameter `dn`

          The distinguished name of the entry.

        Parameter `attr`

          The type (aka name) of the attribute to compare.

        Parameter `value`

          The value to compare with. It's UTF-8 encoded automatically if the attribute syntax specifies that.

        Returns

          Returns `1` if at least one of the values for the attribute in the directory is equal to `value`, `0` if it didn't match or there was some error (use `error_number` to find out).

        Note

          This function has changed arguments since version 7.6. From 7.3 to 7.6 it was effectively useless since it always returned true.

        Note

          The equality matching rule for the attribute governs the comparison. There are attributes where the assertion syntax used here isn't the same as the attribute value syntax.

        Method create

          `Protocols.LDAP.client Protocols.LDAP.client()`
          `Protocols.LDAP.client Protocols.LDAP.client(`string`|`mapping`(`string`:`mixed`) `url`)`
          `Protocols.LDAP.client Protocols.LDAP.client(`string`|`mapping`(`string`:`mixed`) `url`, `object` `context`)`

        Description

          Create object. The first optional argument can be used later for subsequence operations. The second one can specify TLS context of connection. The default context only allows 128-bit encryption methods, so you may need to provide your own context if your LDAP server supports only export encryption.

        Parameter `url`

          LDAP server URL on the form `"ldap://hostname/basedn?attrlist?scope?ext"`. See RFC 2255. It can also be a mapping as returned by `Protocol.LDAP.parse_ldap_url`.

        Parameter `context`

          TLS context of connection

        See also

          `LDAP.client.bind`, `LDAP.client.search`

        Method delete

          ``int` delete(`string` `dn`)`

        Description

          Deletes entry from the LDAP server.

        Parameter `dn`

          The distinguished name of deleted entry.

        Returns

          Returns `1` on success, `0` otherwise.

        Note

          The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

        Method get_attr_type_descr

          ``mapping`(`string`:`mixed`) get_attr_type_descr(`string` `attr`, `void`|`int` `standard_attrs`)`

        Description

          Returns the attribute type description for the given attribute, which includes the name, object identifier, syntax, etc (see section 4.2 in RFC 2252 for details).

          This might do a query to the server, but results are cached.

        Parameter `attr`

          The name of the attribute. Might also be the object identifier on string form.

        Parameter `standard_attrs`

          Flag that controls how the known standard attributes stored in `Protocols.LDAP` are to be used:

          ``0`` | Check the known standard attributes first. If the attribute isn't found there, query the server. This is the default.
          ``1`` | Don't check the known standard attributes, i.e. always use the schema from the server.
          ``2`` | Only check the known standard attributes. The server is never contacted.

        Returns

          Returns a mapping where the indices are the terms that the server has returned and the values are their values on string form (dequoted and converted from UTF-8 as appropriate). Terms without values get `1` as value in the mapping.

          The mapping might contain the following members (all except `"oid"` are optional):

          ``"oid"` : `string``

          The object identifier on string form. According to the RFC, this should always be a dotted decimal string. However some LDAP servers, e.g. iPlanet, allows registering attributes without an assigned OID. In such cases this can be some other string. In the case of iPlanet, it uses the attribute name with "-oid" appended (c.f. http://docs.sun.com/source/816-5606-10/scmacfg.htm).

          ``"NAME"` : `string`` | Array with one or more names used for the attribute.
          ``"DESC"` : `string`` | Description.
          ``"OBSOLETE"` : `string`` | Flag.
          ``"SUP"` : `string`` | Derived from this other attribute. The value is the name or oid of it. Note that the attribute description from the referenced type always is merged with the current one to make the returned description complete.
          ``"EQUALITY"` : `string`` | The value is the name or oid of a matching rule.
          ``"ORDERING"` : `string`` | The value is the name or oid of a matching rule.
          ``"SUBSTR"` : `string`` | The value is the name or oid of a matching rule.
          ``"syntax_oid"` : `string`` | The value is the oid of the syntax (RFC 2252, section 4.3.2). (This is extracted from the `"SYNTAX"` term.)
          ``"syntax_len"` : `string`` | Optional suggested minimum upper bound of the number of characters in the attribute (or bytes if the attribute is binary). (This is extracted from the `"SYNTAX"` term.)
          ``"SINGLE-VALUE"` : `string`` | Flag. Default multi-valued.
          ``"COLLECTIVE"` : `string`` | Flag. Default not collective.
          ``"NO-USER-MODIFICATION"` : `string`` | Flag. Default user modifiable.

          ``"USAGE"` : `string``

          The value is any of the following:

          ``"userApplications"`` | Self-explanatory.
          ``"directoryOperation"``
          ``"distributedOperation"`` | DSA-shared.
          ``"dSAOperation"`` | DSA-specific, value depends on server.

          There might be more fields for server extensions.

          Zero is returned if the server didn't provide any attribute type description for `attr`.

        Note

          It's the schema applicable at the base DN that is queried.

        Note

          LDAPv3 is assumed.

        Method get_basedn

          ``string` get_basedn()`

        Description

          Returns the current base DN for searches using `search` and schema queries using `get_attr_type_descr`.

        Method get_bind_password_hash

          ``string` get_bind_password_hash()`

        Description

          Returns an MD5 hash of the password used for the bind operation, or zero if the connection isn't bound. If no password was given to `bind` then an empty string was sent as password, and the MD5 hash of that is therefore returned.

        Method get_bound_dn

          ``string` get_bound_dn()`

        Description

          Returns the bind DN currently in use for the connection. Zero is returned if the connection isn't bound. The empty string is returned if the connection is in use but no bind DN has been given explicitly to `bind`.

        Method get_cached_filter

          ``object` get_cached_filter(`string` `filter`)`

        Description

          This is a wrapper for `Protocols.LDAP.get_cached_filter` which passes the LDAP protocol version currently in use by this connection.

        Throws

          If there's a parse error in the filter then a `Protocols.LDAP.FilterError` is thrown as from `Protocols.LDAP.make_filter`.

        Method get_default_filter

          ``object` get_default_filter()`

        Description

          Returns the ASN1 object parsed from the filter specified in the LDAP URL, or zero if the URL doesn't specify any filter.

        Throws

          If there's a parse error in the filter then a `Protocols.LDAP.FilterError` is thrown as from `Protocols.LDAP.make_filter`.

        Method get_option

          ``int` get_option(`int` `opttype`)`

        Parameter `option_type`

          LDAP_OPT_xxx

        Method get_parsed_url

          ``mapping`(`string`:`mixed`) get_parsed_url()`

        Description

          Returns a mapping containing the data parsed from the LDAP URL passed to `create`. The mapping has the same format as the return value from `Protocols.LDAP.parse_ldap_url`. Don't be destructive on the returned value.

        Method get_protocol_version

          ``int` get_protocol_version()`

        Description

          Return the LDAP protocol version in use.

        Method get_referrals

          ``array`|`int` get_referrals()`

        Description

          Gets referrals.

        Returns

          Returns array of referrals or `0`.

        Method get_root_dse_attr

          ``array`(`string`) get_root_dse_attr(`string` `attr`)`

        Description

          Returns the value of an attribute in the root DSE (DSA-Specific Entry) of the bound server. The result is cached. A working connection is assumed.

        Returns

          The return value is an array of the attribute values, which have been UTF-8 decoded where appropriate.

          Don't be destructive on the returned array.

        Note

          This function intentionally does not try to simplify the return values for single-valued attributes (c.f. `Protocols.LDAP.SEARCH_MULTIVAL_ARRAYS_ONLY`). That since (at least) Microsoft AD has a bunch of attributes in the root DSE that they don't bother to provide schema entries for. The return value format wouldn't be reliable if they suddenly change that.

        Method get_scope

          ``string` get_scope()`

        Description

          Return the currently set scope as a string `"base"`, `"one"`, or `"sub"`.

        Method get_supported_controls

          ``multiset`(`string`) get_supported_controls()`

        Description

          Returns a multiset containing the controls supported by the server. They are returned as object identifiers on string form. A working connection is assumed.

        See also

          `search`

        Variable info

          ``mapping` Protocols.LDAP.client.info`

        Description

          Several information about code itself and about active connection too

        Inherit protocol

          `inherit .protocol : protocol`

        Method make_filter

          ``object` make_filter(`string` `filter`)`

        Description

          Returns the ASN1 object parsed from the given filter. This is a wrapper for `Protocols.LDAP.make_filter` which parses the filter with the LDAP protocol version currently in use by this connection.

        Throws

          If there's a parse error in the filter then a `Protocols.LDAP.FilterError` is thrown as from `Protocols.LDAP.make_filter`.

        Method modify

          ``int` modify(`string` `dn`, `mapping`(`string`:`array`(`int(0..2)`|`string`)) `attropval`)`

        Description

          The Modify Operation allows a client to request that a modification of an entry be performed on its behalf by a server.

        Parameter `dn`

          The distinguished name of modified entry.

        Parameter `attropval`

          The mapping of attributes with requested operation and attribute's values.

              attropval=([ attribute: ({operation, value1, value2, ...}) ])

          Where operation is one of the following:

          Protocols.LDAP.MODIFY_ADD

            Add values listed to the given attribute, creating the attribute if necessary.

          Protocols.LDAP.MODIFY_DELETE

            Delete values listed from the given attribute, removing the entire attribute if no values are listed, or if all current values of the attribute are listed for deletion.

          Protocols.LDAP.MODIFY_REPLACE

            Replace all existing values of the given attribute with the new values listed, creating the attribute if it did not already exist. A replace with no value will delete the entire attribute if it exists, and is ignored if the attribute does not exist.

          Values that are sent UTF-8 encoded according the the attribute syntaxes are encoded automatically.

        Returns

          Returns `1` on success, `0` otherwise.

        Note

          The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

        Method modifydn

          ``int` modifydn(`string` `dn`, `string` `newrdn`, `int` `deleteoldrdn`, `string`|`void` `newsuperior`)`

        Description

          The Modify DN Operation allows a client to change the leftmost (least significant) component of the name of an entry in the directory, or to move a subtree of entries to a new location in the directory.

        Parameter `dn`

          DN of source object

        Parameter `newrdn`

          RDN of destination

        Parameter `deleteoldrdn`

          The parameter controls whether the old RDN attribute values are to be retained as attributes of the entry, or deleted from the entry.

        Parameter `newsuperior`

          If present, this is the Distinguished Name of the entry which becomes the immediate superior of the existing entry.

        Returns

          Returns `1` on success, `0` otherwise.

        Note

          The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

        Method parse_url

          ``mapping`(`string`:`mixed`) parse_url(`string` `ldapuri`)`

        Description

          Compatibility alias for `Protocols.LDAP.parse_ldap_url`.

        Method read

          ``mapping`(`string`:`string`|`array`(`string`)) read(`string` `object_name`, `void`|`string` `filter`, `void`|`array`(`string`) `attrs`, `void`|`int` `attrsonly`, `void`|`mapping`(`string`:`array`(`int`|`string`)) `controls`, `void`|`int` `flags`)`

        Description

          Reads a specified object in the LDAP server. `object_name` is the distinguished name for the object. The rest of the arguments are the same as to `search`.

          The default filter and attributes that might have been set in the LDAP URL doesn't affect this call. If `filter` isn't set then `"(objectClass=*)"` is used.

        Returns

          Returns a mapping of the requested attributes. It has the same form as the response from `result.fetch`.

        See also

          `search`

        Method read_attr

          ``string`|`array`(`string`) read_attr(`string` `object_name`, `string` `attr`, `void`|`string` `filter`, `void`|`mapping`(`string`:`array`(`int`|`string`)) `controls`)`

        Description

          Reads a specified attribute of a specified object in the LDAP server. `object_name` is the distinguished name of the object and `attr` is the attribute. The rest of the arguments are the same as to `search`.

          The default filter that might have been set in the LDAP URL doesn't affect this call. If `filter` isn't set then `"(objectClass=*)"` is used.

        Returns

          For single-valued attributes, the value is returned as a string. For multivalued attributes, the value is returned as an array of strings. Returns zero if there was an error.

        See also

          `read`, `get_root_dse_attr`

        Method reset_options

          ``void` reset_options()`

        Description

          Resets all connection options, such as the scope and the base DN, to the defaults determined from the LDAP URL when the connection was created.

        Method search

          ``result`|`int` search(`string`|`object`|`void` `filter`, `array`(`string`)|`void` `attrs`, `int`|`void` `attrsonly`, `void`|`mapping`(`string`:`array`(`int`|`string`)) `controls`, `void`|`int` `flags`)`

        Description

          Search LDAP directory.

        Parameter `filter`

          Search filter to override the one from the LDAP URL. It's either a string with the format specified in RFC 2254, or an object returned by `Protocols.LDAP.make_filter`.

        Parameter `attrs`

          The array of attribute names which will be returned by server for every entry.

        Parameter `attrsonly`

          This flag causes server return only the attribute types (aka names) but not their values. The values will instead be empty arrays or - if `Protocols.LDAP.SEARCH_MULTIVAL_ARRAYS_ONLY` is given - zeroes for single-valued attributes.

        Parameter `controls`

          Extra controls to send in the search query, to modify how the server executes the search in various ways. The value is a mapping with an entry for each control.

          ``object_identifier` : `string``

          The index is the object identifier in string form for the control type. There are constants in `Protocols.LDAP` for the object identifiers for some known controls.

          The mapping value is an array of two elements:

          Array
          ``int` `0`` | The first element is an integer flag that specifies whether the control is critical or not. If it is nonzero, the server returns an error if it doesn't understand the control. If it is zero, the server ignores it instead.
          ``string`|`int(0..0)` `1`` | The second element is the string value to pass with the control. It may also be zero to not pass any value at all.

        Parameter `flags`

          Bitfield with flags to control various behavior at the client side of the search operation. See the `Protocol.LDAP.SEARCH_*` constants for details.

        Returns

          Returns object `LDAP.client.result` on success, `0` otherwise.

        Note

          The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

        See also

          `result`, `result.fetch`, `read`, `get_supported_controls`, `Protocols.LDAP.ldap_encode_string`, `Protocols.LDAP.make_filter`

        Method set_basedn

          ``string` set_basedn(`string` `base_dn`)`

        Description

          Sets the base DN for searches using `search` and schema queries using `get_attr_type_descr`.

        Note

          For compatibility, the old base DN is returned. However, if LDAPv3 is used, the value is UTF-8 encoded. Use `get_basedn` separately instead.

        Method set_option

          ``int` set_option(`int` `opttype`, `int` `value`)`

        Parameter `option_type`

          LDAP_OPT_xxx

        Parameter `value`

          new value for option

        Method set_scope

          ``int` set_scope(`int`|`string` `scope`)`

        Description

          Sets value of scope for search operation.

        Parameter `scope`

          The value can be one of the `SCOPE_*` constants or a string `"base"`, `"one"` or `"sub"`.

        Returns

          Returns the `SCOPE_*` constant for the old scope.

        Method start_tls

          ``int` start_tls(`void`|`SSL.Context` `context`)`

        Description

          Requests that a SSL/TLS session be negotiated on the connection. If the connection is already secure, this call will fail.

        Parameter `context`

          an optional SSL.context object to provide to the SSL/TLS connection client.

          Returns `1` on success, `0` otherwise.

        Method unbind

          ``int` unbind()`

        Description

          Unbinds from the directory and close the connection.

        ## Class Protocols.LDAP.client.result

          Description

            Contains the result of a LDAP search.

          See also

            `LDAP.client.search`, `LDAP.client.result.fetch`

          Method count_entries

            ``int` count_entries()`

          Description

            Returns the number of entries from the current cursor position to the end of the list.

          See also

            `LDAP.client.result.first`, `LDAP.client.result.next`

          Method create

            `Protocols.LDAP.client.result Protocols.LDAP.client.result(`array`(`object`) `entries`, `int` `stuff`, `int` `flags`)`

          Description

            You can't create instances of this object yourself. The only way to create it is via a search of a LDAP server.

          Method error_number

            ``int` error_number()`

          Description

            Returns the error number in the search result.

          See also

            `error_string`, `server_error_string`

          Method error_string

            ``string` error_string()`

          Description

            Returns the description of the error in the search result. This is the error string from the server, or a standard error message corresponding to the error number if the server didn't provide any description.

          See also

            `server_error_string`, `error_number`

          Method fetch

            ``ResultEntry` fetch(`int`|`void` `idx`)`

          Description

            Returns the current entry pointed to by the cursor.

          Parameter `index`

            This optional argument can be used for direct access to an entry other than the one currently pointed to by the cursor.

          Returns

            The return value is a mapping describing the entry:

            ``attribute` : `string``

            An attribute in the entry. The value is an array containing the returned attribute value(s) on string form, or a single string if `Protocols.LDAP.SEARCH_MULTIVAL_ARRAYS_ONLY` was given to `search` and the attribute is typed as single valued.

            If `Protocols.LDAP.SEARCH_RETURN_DECODE_ERRORS` was given to `search` then `Charset.DecodeError` objects are returned in place of a string whenever an attribute value fails to be decoded.

            ``"dn"` : `string`` | This special entry contains the object name of the entry as a distinguished name. This might also be a `Charset.DecodeError` if `Protocols.LDAP.SEARCH_RETURN_DECODE_ERRORS` was given to `search`.

            Zero is returned if the cursor is outside the valid range of entries.

          Throws

            Unless `Protocols.LDAP.SEARCH_RETURN_DECODE_ERRORS` was given to `search`, a `Charset.DecodeError` is thrown if there is an error decoding the DN or any attribute value.

          Note

            It's undefined whether or not destructive operations on the returned mapping will affect future `fetch` calls for the same entry.

          Note

            In Pike 7.6 and earlier, the special `"dn"` entry was incorrectly returned in UTF-8 encoded form for LDAPv3 connections.

          See also

            `fetch_all`

          Method fetch_all

            ``array`(`ResultEntry`) fetch_all()`

          Description

            Convenience function to fetch all entries at once. The cursor isn't affected.

          Returns

            Returns an array where each element is the entry from the result. Don't be destructive on the returned value.

          Throws

            Unless `Protocols.LDAP.SEARCH_RETURN_DECODE_ERRORS` was given to `search`, a `Charset.DecodeError` is thrown if there is an error decoding the DN or any attribute value.

          See also

            `fetch`

          Method first

            ``void` first()`

          Description

            Initialized the result cursor to the first entry in the result list.

          See also

            `LDAP.client.result.next`

          Method get_dn

            ``string`|`Charset.DecodeError` get_dn()`

          Description

            Returns distinguished name (DN) of the current entry in the result list. Note that this is the same as getting the `"dn"` field from the return value from `fetch`.

          Note

            In Pike 7.6 and earlier, this field was incorrectly returned in UTF-8 encoded form for LDAPv3 connections.

          Method next

            ``int` next()`

          Description

            Moves the result cursor to the next entry in the result list. Returns number of remained entries in the result list. Returns 0 at the end.

          See also

            `LDAP.client.result.next`

          Method num_entries

            ``int` num_entries()`

          Description

            Returns the number of entries.

          See also

            `LDAP.client.result.count_entries`

          Method server_error_string

            ``string` server_error_string()`

          Description

            Returns the error string from the server, or zero if the server didn't provide any.

          See also

            `error_string`, `error_number`

      ## Class Protocols.LDAP.protocol

        Method error_number

          ``int` error_number()`

        Description

          Returns the error number from the last transaction. If the error is `LDAP_SERVER_DOWN` then there was a socket error, and the I/O error number can be retrieved using ``ldapfd`->errno()`.

        See also

          `error_string`, `server_error_string`

        Method error_string

          ``string` error_string()`

        Description

          Returns the description of the error from the last transaction. This is the error string from the server, or a standard error message corresponding to the error number if the server didn't provide any description.

          If `error_number` returns `LDAP_SERVER_DOWN` then this is the `strerror` message corresponding to the I/O error for the connection.

        See also

          `server_error_string`, `error_number`

        Method get_last_io_time

          ``int` get_last_io_time()`

        Description

          Returns when I/O was made last. Useful to find out whether it's safe to continue using a connection that has been idle for some time.

        Method server_error_string

          ``string` server_error_string()`

        Description

          Returns the error string from the server, or zero if the server didn't provide any.

        See also

          `error_string`, `error_number`

    ## Module Protocols.LMTP

      ## Class Protocols.LMTP.Server

        Description

          A LMTP server. It has been fairly well tested against Postfix client. Actually this module is only an extention to the `SMTP` server.

        Method create

          `Protocols.LMTP.Server Protocols.LMTP.Server(`array`(`string`) `_domains`, `void`|`int` `port`, `void`|`string` `ip`, `function`(:`void`) `_cb_mailfrom`, `function`(:`void`) `_cb_rcptto`, `function`(:`void`) `_cb_data`)`

        Description

          Create a receiving LMTP server. It implements RFC 2821, 2822, 2033 and 1854.

        Parameter `domain`

          Domains name this server relay, you need to provide at least one domain (the first one will be used for MAILER-DAEMON address). if you want to relay everything you can put a '*' after this first domain.

        Parameter `port`

          Port this server listen on

        Parameter `listenip`

          IP on which server listen

        Parameter `cb_mailfrom`

          Mailfrom callback function, this function will be called when a client send a mail from command. This function must take a string as argument (corresponding to the sender's email) and return int corresponding to the SMTP code to output to the client. If you return an array the first element is the SMTP code and the second is the error string to display.

        Parameter `cb_rcptto`

          Same as cb_mailfrom but called when a client sends a rcpt to.

        Parameter `cb_data`

          This function is called for each recipient in the "rcpt to" command after the client sends the "data" command It must have the following synopsis: int|array cb_data(object mime, string sender, string recipient, void|string rawdata) object mime : the mime data object string sender : sender of the mail (from the mailfrom command) string recipient : one recipient given by one rcpt command. return : SMTP code to output to the client. If you return an array the first element is the SMTP code and the second is the error string to display. Note that to comply with LMTP protocol you must output a code each time this function is called.

        Example

              Here is an example of silly program that does nothing except outputing
                informations to stdout.
               int cb_mailfrom(string mail)
               {
                 return 250;
               }
               int cb_rcptto(string email)
               {
                 // check the user's mailbox here
                 return 250;
               }
               int cb_data(object mime, string sender, string recipient)
               {
                 write(sprintf("smtpd: mailfrom=%s, to=%s, headers=%O\ndata=%s\n",
                 sender, recipient, mime->headers, mime->getdata()));
                 // check the data and deliver the mail here
                 if(mime->body_parts)
                 {
                 {
                   foreach(mime->body_parts, object mpart)
                     write(sprintf("smtpd: mpart data = %O\n", mpart->getdata()));
                 }
                 return 250;
               }
               int main(int argc, array(string) argv)
               {
                 Protocols.LMTP.Server(({ "ece.fr" }), 2500, "127.0.0.1",       cb_mailfrom, cb_rcptto, cb_data);
                 return -1;
               }

    ## Module Protocols.LPD

      Description

        An implementation of the BSD lpd protocol (RFC 1179).

      ## Class Protocols.LPD.client

        Description

          A client for communicating with printers and print spoolers that support the BSD lpd protocol (RFC 1179).

        Method create

          `Protocols.LPD.client Protocols.LPD.client(`string`|`void` `hostname`, `int`|`void` `portnum`)`

        Description

          Create a new LPD client connection.

        Parameter `hostname`

          Contains the hostname or ipaddress of the print host. if not provided, defaults to localhost.

        Parameter `portnum`

          Contains the port the print host is listening on. if not provided, defaults to port 515, the RFC 1179 standard.

        Method delete_job

          ``int` delete_job(`string` `queue`, `int`|`void` `job`)`

        Description

          Delete job job from printer queue.

        Returns

          Returns 1 on success, 0 otherwise.

        Method send_job

          ``string`|`int` send_job(`string` `queue`, `string` `job`)`

        Description

          Send print job consisting of data job to printer queue.

        Returns

          Returns 1 if success, 0 otherwise.

        Method set_job_name

          ``int` set_job_name(`string` `name`)`

        Description

          Sets the name of the print job to name.

        Method set_job_type

          ``int` set_job_type(`string` `type`)`

        Description

          Set the type of job to be sent to the printer to type. Valid types are: text, postscript and raw.

        Method start_queue

          ``int` start_queue(`string` `queue`)`

        Description

          Start the queue queue if not already printing.

        Returns

          Returns 0 if unable to connect, 1 otherwise.

        Method status

          ``string`|`int` status(`string` `queue`)`

        Description

          Check the status of queue queue.

        Returns

          Returns 0 on failure, otherwise returns the status response from the printer.

    ## Module Protocols.Line

      ## Class Protocols.Line.imap_style

        Description

          Nonblocking line-oriented I/O with support for reading literals.

        Method expect_literal

          ``void` expect_literal(`int` `length`, `function`(`string`:`void`) `callback`)`

        Description

          Enter literal reading mode.

          Sets `literal_length` and `handle_literal()`.

        See also

          `literal_length`, `handle_literal()`

        Method handle_command

          ``void` handle_command(`string` `line`)`

        Description

          Function called once for every received line.

        Variable handle_line

          ``function`(`string`:`void`) Protocols.Line.imap_style.handle_line`

        Description

          This function will be called once for every line that is received.

        Note

          This API is provided for backward compatibility; overload `handle_command()` instead.

        See also

          `Protocols.Line.simple()->handle_command()`

        Variable handle_literal

          ``function`(`string`:`void`) Protocols.Line.imap_style.handle_literal`

        Description

          If this variable has been set, `literal_length` bytes will be accumulated, and this function will be called with the resulting data.

        Note

          `handle_literal()` is one-shot, ie it will be cleared when it is called.

        Inherit simple

          `inherit simple : simple`

        Variable literal_length

          ``int` Protocols.Line.imap_style.literal_length`

        Description

          Length in bytes of the literal to read.

      ## Class Protocols.Line.simple

        Description

          Simple nonblocking line-oriented I/O.

        Method close_callback

          ``protected` `void` close_callback()`

        Description

          This function is called when the connection has been closed at the other end.

          Overload this function as appropriate.

          The default action is to shut down the connection on this side as well.

        Method create

          `Protocols.Line.simple Protocols.Line.simple(`Stdio.File` `con`, `int`|`void` `timeout`)`

        Description

          Create a simple nonblocking line-based protocol handler.

          `con` is the connection.

          `timeout` is an optional timeout in seconds after which the connection will be closed if there has been no data sent or received.

          If `timeout` is `0` (zero), no timeout will be in effect.

        See also

          `touch_time()`, `do_timeout()`

        Method disconnect

          ``void` disconnect()`

        Description

          Disconnect the connection.

          Pushes an end of file marker onto the send queue `send_q`.

        Note

          Note that the actual closing of the connection is delayed until all data in the send queue has been sent.

          No more data will be read from the other end after this function has been called.

        Method do_timeout

          ``protected` `void` do_timeout()`

        Description

          This function is called when a timeout occurrs.

          Overload this function as appropriate.

          The default action is to shut down the connection immediately.

        See also

          `create()`, `touch_time()`

        Method handle_command

          ``void` handle_command(`string` `line`)`

        Description

          This function will be called once for every line that is received.

          Overload this function as appropriate.

        Note

          It will not be called if `handle_data()` has been set.

          `line` will not contain the line separator.

        See also

          `handle_data()`

        Variable handle_data

          ``function`(`string`:`void`) Protocols.Line.simple.handle_data`

        Description

          If this variable has been set, multiple lines will be accumulated, until a line with a single `"."` (period) is received. `handle_data()` will then be called with the accumulated data as the argument.

        Note

          `handle_data()` is one-shot, ie it will be cleared when it is called.

          The line with the single `"."` (period) will not be in the accumulated data.

        See also

          `handle_command()`

        Constant line_separator

          ```protected` constant` `string` Protocols.Line.simple.`line_separator``

        Description

          The sequence separating lines from eachother. "\r\n" by default.

        Method read_callback

          ``protected` `void` read_callback(`mixed` `ignored`, `string` `data`)`

        Description

          Called when data has been received.

          Overload as appropriate.

          Calls the handle callbacks repeatedly until no more lines are available.

        See also

          `handle_data()`, `handle_command()`, `read_line()`

        Method read_line

          ``protected` `string` read_line()`

        Description

          Read a line from the input.

        Returns

          Returns `0` when more input is needed. Returns the requested line otherwise.

        Note

          The returned line will not contain the line separator.

        See also

          `handle_command()`, `line_separator`

        Method send

          ``protected` `void` send(`string` `s`)`

        Description

          Queue some data to send.

        See also

          `handle_command()`, `handle_data()`, `disconnect()`

        Variable send_q

          ``ADT.Queue` Protocols.Line.simple.send_q`

        Description

          Queue of data that is pending to send.

          The elements in the queue are either strings with data to send, or `0` (zero) which is the end of file marker. The connection will be closed when the end of file marker is reached.

        See also

          `send()`, `disconnect()`

        Method touch_time

          ``void` touch_time()`

        Description

          Reset the timeout timer.

        See also

          `create()`, `do_timeout()`

      ## Class Protocols.Line.smtp_style

        Description

          Nonblocking line-oriented I/O with support for sending SMTP-style codes.

        Variable errorcodes

          ``mapping`(`int`:`string`|`array`(`string`)) Protocols.Line.smtp_style.errorcodes`

        Description

          Mapping from return-code to error-message.

          Overload this constant as apropriate.

        Inherit simple

          `inherit simple : simple`

        Method send

          ``void` send(`int(100..999)` `code`, `array`(`string`)|`string`|`void` `lines`)`

        Description

          Send an SMTP-style return-code.

          `code` is an SMTP-style return-code.

          If `lines` is omitted, `errorcodes` will be used to lookup an appropriate error-message.

          If `lines` is a string, it will be split on `"\n"` (newline), and the error-code interspersed as appropriate.

        See also

          `errorcodes`

    ## Module Protocols.NNTP

      Description

        NNTP - The Network News Transfer Protocol.

      ## Class Protocols.NNTP.asyncprotocol

        Description

          Asynchronous NNTP protocol

        Method command

          ``void` command(`string` `cmd`, `function`(:`void`)|`void` `cb`)`

        Description

          send a command to the server

        Returns

          the result code sent by the server

        Inherit protocolhelper

          `inherit protocolhelper : protocolhelper`

        Inherit sock

          `inherit Stdio.File : sock`

        Method readreturncode

          ``void` readreturncode(`function`(:`void`) `cb`, `mixed` ... `extra`)`

        Description

          reads the server result code for last request used internally by command().

      ## Class Protocols.NNTP.client

        Description

          An NNTP client

        Method article

          ``string` article(`void`|`int`|`string` `x`)`

        Method body

          ``string` body(`void`|`int`|`string` `x`)`

        Method create

          `Protocols.NNTP.client Protocols.NNTP.client(`string`|`void` `server`)`

        Parameter `server`

          NNTP server to connect to. Defaults to the server specified by the environment variable `NNTPSERVER`.

        Variable current_group

          ``Group` Protocols.NNTP.client.current_group`

        Description

          The current news group.

        Method go_to_group

          ``Group` go_to_group(`string` `group`)`

        Description

          Sets the current group to `group`.

        Method head

          ``string` head(`void`|`int`|`string` `x`)`

        Inherit protocol

          `inherit protocol : protocol`

        Method list_groups

          ``array`(`Group`) list_groups()`

        Description

          Returns a list of all active groups.

        Method set_group

          ``void` set_group(`Group` `o`)`

        Description

          Sets the current news group to `o`.

      ## Class Protocols.NNTP.protocol

        Description

          Synchronous NNTP protocol

        Method command

          ``int` command(`string` `cmd`)`

        Description

          send a command to the server

        Returns

          the result code sent by the server

        Method do_cmd_with_body

          ``string` do_cmd_with_body(`string` `cmd`)`

        Description

          send a command that should return a message body.

        Returns

          the message body

        Method failsafe_command

          ``int` failsafe_command(`string` `cmd`)`

        Description

          send a command and require an ok response (200 series). throws an error if the command result was not success.

        Inherit protocolhelper

          `inherit protocolhelper : protocolhelper`

        Inherit sock

          `inherit Stdio.FILE : sock`

        Method read_body_lines

          ``array`(`string`) read_body_lines()`

        Description

          reads the message from the server as an array of lines

        Method readreturnbody

          ``string` readreturnbody()`

        Description

          reads the message from the server

        Method readreturncode

          ``int` readreturncode()`

        Description

          reads the server result code for last request used internally by command().

        Method writebody

          ``void` writebody(`string` `s`)`

        Description

          send the body of a message to the server.

      ## Class Protocols.NNTP.protocolhelper

        Description

          helper class for protocol implementations.

        See also

          `protocol`

        Method get_response_message

          ``string` get_response_message()`

        Description

          gets the result message supplied by the server for the last response

    ## Module Protocols.OBEX

      Description

        The IrDA® Object Exchange Protocol. OBEX is a protocol for sending and receiving binary objects to mobile devices using transports such as IR and Bluetooth.

      Typedef Headers

        ``typedef` `mapping`(`HeaderIdentifier`:`string`|`int`|`array`) Protocols.OBEX.`Headers``

      Description

        A set of request or response headers. Each HI can be associated with either a single value (int or string, depending on the HI in question) or an array with multiple such values.

      Constant SETPATH_BACKUP

        ```final` constant` `int` Protocols.OBEX.`SETPATH_BACKUP``

      Description

        A flag for the `REQ_SETPATH` command indicating that the parent directory should be selected

      Constant SETPATH_NOCREATE

        ```final` constant` `int` Protocols.OBEX.`SETPATH_NOCREATE``

      Description

        A flag for the `REQ_SETPATH` command indicating that the selected directory should not be created if it doesn't exist

      Method decode_headers

        ``Headers` decode_headers(`string` `h`)`

      Description

        Deserialize a set of headers from wire format

      Method encode_headers

        ``string` encode_headers(`Headers` `h`)`

      Description

        Serialize a set of headers to wire format

      See also

        `split_headers()`

      Method split_headers

        ``array`(`string`) split_headers(`string` `h`, `int` `chunklen`)`

      Description

        Given a set of headers in wire format, divide them into portions of no more than `chunklen` octets each (if possible). No individual header definition will be split into two portions.

      ## Enum Protocols.OBEX.HeaderIdentifier

        Description

          An identifier for a request or response header

        Constant HI_APPPARAM

          ``constant` Protocols.OBEX.`HI_APPPARAM``

        Description

          Extended application request & response information

        Constant HI_AUTHCHALL

          ``constant` Protocols.OBEX.`HI_AUTHCHALL``

        Description

          Authentication digest-challenge

        Constant HI_AUTHRESP

          ``constant` Protocols.OBEX.`HI_AUTHRESP``

        Description

          Authentication digest-response

        Constant HI_BODY

          ``constant` Protocols.OBEX.`HI_BODY``

        Description

          A chunk of the object body

        Constant HI_CONNID

          ``constant` Protocols.OBEX.`HI_CONNID``

        Description

          An identifier used for OBEX connection multiplexing

        Constant HI_COUNT

          ``constant` Protocols.OBEX.`HI_COUNT``

        Description

          Number of objects to transfer (used by `REQ_CONNECT`)

        Constant HI_CREATORID

          ``constant` Protocols.OBEX.`HI_CREATORID``

        Description

          Indicates the creator of an object

        Constant HI_DESCRIPTION

          ``constant` Protocols.OBEX.`HI_DESCRIPTION``

        Description

          Text description of the object

        Constant HI_ENDOFBODY

          ``constant` Protocols.OBEX.`HI_ENDOFBODY``

        Description

          The final chunk of the object body

        Constant HI_HTTP

          ``constant` Protocols.OBEX.`HI_HTTP``

        Description

          Any HTTP 1.x header

        Constant HI_LENGTH

          ``constant` Protocols.OBEX.`HI_LENGTH``

        Description

          Length of the object transferred, in octets

        Constant HI_NAME

          ``constant` Protocols.OBEX.`HI_NAME``

        Description

          Name of the object (string)

        Constant HI_OBJCLASS

          ``constant` Protocols.OBEX.`HI_OBJCLASS``

        Description

          OBEX object class of object

        Constant HI_SESSPARAM

          ``constant` Protocols.OBEX.`HI_SESSPARAM``

        Description

          Parameters used in session commands/responses

        Constant HI_SESSSEQNR

          ``constant` Protocols.OBEX.`HI_SESSSEQNR``

        Description

          Sequence number used in each OBEX packet for reliability

        Constant HI_TARGET

          ``constant` Protocols.OBEX.`HI_TARGET``

        Description

          Name of service that operation is targeted to

        Constant HI_TIME

          ``constant` Protocols.OBEX.`HI_TIME``

        Description

          ISO 8601 timestamp (string)

        Constant HI_TYPE

          ``constant` Protocols.OBEX.`HI_TYPE``

        Description

          Type of the object (IANA media type)

        Constant HI_WANUUID

          ``constant` Protocols.OBEX.`HI_WANUUID``

        Description

          Uniquely identifies the OBEX server

        Constant HI_WHO

          ``constant` Protocols.OBEX.`HI_WHO``

        Description

          Identifies the OBEX application (string)

      ## Enum Protocols.OBEX.Request

        Description

          A request opcode, for use with the `client.do_request()` function.

        Constant REQ_ABORT

          ``constant` Protocols.OBEX.`REQ_ABORT``

        Description

          Abort the request currently being processed

        Constant REQ_CONNECT

          ``constant` Protocols.OBEX.`REQ_CONNECT``

        Description

          Establish a new OBEX connection

        Constant REQ_DISCONNECT

          ``constant` Protocols.OBEX.`REQ_DISCONNECT``

        Description

          Terminate an OBEX connection

        Constant REQ_FINAL

          ``constant` Protocols.OBEX.`REQ_FINAL``

        Description

          For `REQ_PUT` and `REQ_GET` requests, REQ_FINAL must be set for the request block containing the last portion of the headers. Other requests must be sent as a single block and have the REQ_FINAL bit encoded in their request opcode.

        Constant REQ_GET

          ``constant` Protocols.OBEX.`REQ_GET``

        Description

          Receive an object from the mobile devuce

        Constant REQ_PUT

          ``constant` Protocols.OBEX.`REQ_PUT``

        Description

          Send an object to the mobile device

        Constant REQ_SESSION

          ``constant` Protocols.OBEX.`REQ_SESSION``

        Description

          Manage a session

        Constant REQ_SETPATH

          ``constant` Protocols.OBEX.`REQ_SETPATH``

        Description

          Change the working directory

      ## Class Protocols.OBEX.ATClient

        Description

          An extension of the `client` which uses the AT*EOBEX modem command to enter OBEX mode. Use together with Sony Ericsson data cables.

        Inherit Client

          `inherit Client : Client`

      ## Class Protocols.OBEX.Client

        Description

          An OBEX client

        See also

          `ATclient`

        Method connect

          ``bool` connect()`

        Description

          Establish a new connection using the `REQ_CONNECT` opcode to negotiate transfer parameters

        Returns

          If the connection succeeds, 1 is returned. Otherwise, 0 is returned.

        Method create

          `Protocols.OBEX.Client Protocols.OBEX.Client(`Stdio.Stream` `_con`)`

        Description

          Initialize the client by establishing a connection to the server at the other end of the provided transport stream

        Parameter `_con`

          A stream for writing requests and reading back responses. Typically this is some kind of serial port.

        Method disconnect

          ``bool` disconnect()`

        Description

          Terminate a connection using the `REQ_DISCONNECT` opcode

        Returns

          If the disconnection succeeds, 1 is returned. Otherwise, 0 is returned.

        Method do_abort

          ``array`(`int`|`Headers`) do_abort(`Headers`|`void` `headers`)`

        Description

          Perform a `REQ_ABORT` request.

        See also

          `do_request()`

        Method do_get

          ``array`(`int`|`Headers`) do_get(`Stdio.Stream` `data`, `Headers`|`void` `headers`)`

        Description

          Perform a `REQ_GET` request.

        Parameter `data`

          A stream to write the body data to

        Parameter `headers`

          Headers for the request

        Returns

          See `do_request()`. The Headers do not contain any `HI_BODY` headers, they are written to the `data` stream.

        See also

          `do_put()`, `do_request()`

        Method do_put

          ``array`(`int`|`Headers`) do_put(`string`|`Stdio.Stream` `data`, `Headers`|`void` `extra_headers`)`

        Description

          Perform a `REQ_PUT` request.

        Parameter `data`

          Body data to send, or a stream to read the data from

        Parameter `extra_headers`

          Any additional headers to send (`HI_LENGTH` and `HI_BODY` are generated by this function)

        See also

          `do_get()`, `do_request()`

        Method do_request

          ``array`(`int`|`Headers`) do_request(`Request` `r`, `Headers`|`void` `headers`, `string`|`void` `extra_req`)`

        Description

          Perform a request/response exchange with the server, including processing of headers and request splitting.

        Parameter `r`

          Request opcode

        Parameter `headers`

          Request headers

        Parameter `extra_req`

          Any request data that should appear before the headers, but after the opcode

        Returns

          An array with the response information

          Array
          ``int` `returncode`` | An HTTP response code
          ``Headers` `headers`` | Response headers

        See also

          `low_do_request()`, `do_abort()`, `do_put()`, `do_get()`, `do_setpath()`, `do_session()`

        Method do_session

          ``array`(`int`|`Headers`) do_session(`Headers`|`void` `headers`)`

        Description

          Perform a `REQ_SESSION` request.

        See also

          `do_request()`

        Method do_setpath

          ``array`(`int`|`Headers`) do_setpath(`string` `path`, `int`|`void` `flags`, `Headers`|`void` `extra_headers`)`

        Description

          Perform a `REQ_SETPATH` request.

        Parameter `path`

          The directory to set as current working directory

          ``"/"`` | Go to the root directory
          ``".."`` | Go to the parent directory

        Parameter `flags`

          Logical or of zero or more of `SETPATH_BACKUP` and `SETPATH_NOCREATE`

        Parameter `extra_headers`

          Any additional request headers (the `HI_NAME` header is generated by this function)

        See also

          `do_request()`

        Method low_do_request

          ``array`(`int`|`string`) low_do_request(`Request` `r`, `string` `data`)`

        Description

          Perform a request/response exchange with the server. No interpretation is preformed of either the request or response data, they are just passed literally.

        Parameter `r`

          Request opcode

        Parameter `data`

          Raw request data

        Returns

          An array with the response information

          Array
          ``int` `returncode`` | An HTTP response code
          ``string` `data`` | Response data, if any

        See also

          `do_request()`

    ## Module Protocols.Ports

      Description

        A list of named ports. This is similar to /etc/services.

      Method `[]

        ``Service`|`mixed` `[](`string` `name`)`

      Description

        If `name` is not an indentifier in this module, return the first matching protocol. This would be the first element in the array returned by `lookup`

      Method lookup

        ``array`(`Service`) lookup(`string` `name`)`

      Description

        Return all ports registered for the specified name This function also reads data from /etc/services if possible.

      Method port

        ``int` port(`string` `name`)`

      Description

        Return the first port registered for the specified name (the lowest numbered tcp port, or if there is no tcp ports, the lowest numbered udp port)

      Constant private_tcp

        ``constant` Protocols.Ports.`private_tcp``

      Description

        Contains all TCP ports assigned for private use as of RFC 1700

      Constant private_udp

        ``constant` Protocols.Ports.`private_udp``

      Description

        Contains all UDP ports assigned for private use as of RFC 1700

      Constant tcp

        ``constant` Protocols.Ports.`tcp``

      Description

        Contains all non-private TCP port assignments as of RFC 1700 Extended with some non-official.

      Constant udp

        ``constant` Protocols.Ports.`udp``

      Description

        Contains all non-private UDP port assignments as of RFC 1700

      ## Class Protocols.Ports.Service

        Description

          A single service registration. Used as the return value for the `lookup` method.

        Variable name
        Variable port
        Variable protocol
        Variable comment

          ``string` Protocols.Ports.Service.name`
          ``int` Protocols.Ports.Service.port`
          ``string` Protocols.Ports.Service.protocol`
          ``string` Protocols.Ports.Service.comment`

        Method create

          `Protocols.Ports.Service Protocols.Ports.Service(`string` `name`, `int` `port`, `string` `protocol`, `string` `comment`)`

    ## Module Protocols.SMTP

      Variable replycodes

        ``mapping`(`int`:`string`) Protocols.SMTP.replycodes`

      Description

        A mapping(int:string) that maps SMTP return codes to english textual messages.

      ## Class Protocols.SMTP.AsyncClient

        Description

          Asynchronous (nonblocking/event-oriented) email client class (this lets you send emails).

        Method create

          `Protocols.SMTP.AsyncClient Protocols.SMTP.AsyncClient(`void`|`string`|`object` `server`, `int`|`void` `port`, `function`(:`void`)|`void` `cb`, `mixed` ... `args`)`

        Description

          Creates an SMTP mail client and connects it to the the `server` provided. The server parameter may either be a string with the hostname of the mail server, or it may be a file object acting as a mail server. If `server` is a string, then an optional port parameter may be provided. If no port parameter is provided, port 25 is assumed. If no parameters at all is provided the client will look up the mail host by searching for the DNS MX record.

          The callback will first be called when the connection is established (`cb(1, @args)`) or fails to be established with an error. The callback will also be called with an error if one occurs during the delivery of mails.

          In the error cases, the `cb` gets called the following ways:

          - `cb(({ 1, errno(), error_string, int(0..1) direct }), @args);`

          - `cb(({ 0, smtp-errorcode, error_string, int(0..1) direct }), @args);`

          Where `direct` is `1` if establishment of the connection failed.

        Inherit AsyncProtocol

          `inherit AsyncProtocol : AsyncProtocol`

        Inherit ClientHelper

          `inherit ClientHelper : ClientHelper`

        Method send_message

          ``void` send_message(`string` `from`, `array`(`string`) `to`, `string` `body`, `function`(:`void`)|`void` `cb`, `mixed` ... `args`)`

        Description

          Sends a mail message from `from` to the mail addresses listed in `to` with the mail body `body`. The body should be a correctly formatted mail DATA block, e.g. produced by `MIME.Message`.

          When the message is successfully sent, the callback will be called (`cb(1, @args);`).

          When the message cannot be sent, `cb` will be called in one of the following ways:

          - `cb(({ 1, errno(), error_string, int(0..1) direct }), @args);`

          - `cb(({ 0, smtp-errorcode, error_string, int(0..1) direct }), @args);`

          where direct will be `1` if this particular message caused the error and `0` otherwise.

        See also

          `simple_mail`

        Method simple_mail

          ``void` simple_mail(`string` `to`, `string` `subject`, `string` `from`, `string` `msg`, `function`(:`void`)|`void` `cb`, `mixed` ... `args`)`

        Description

          Sends an e-mail. Wrapper function that uses `send_message`.

        Note

          Some important headers are set to: `"Content-Type: text/plain; charset=iso-8859-1"` and `"Content-Transfer-Encoding: 8bit"`. `"Date:"` header isn't used at all.

          When the message is successfully sent, the callback will be called (`cb(1, @args);`).

          When the message cannot be sent, `cb` will be called in one of the following ways:

          - `cb(({ 1, errno(), error_string, int(0..1) direct }), @args);`

          - `cb(({ 0, smtp-errorcode, error_string, int(0..1) direct }), @args);`

          where direct will be `1` if this particular message caused the error and `0` otherwise.

        Method verify

          ``void` verify(`string` `addr`, `function`(:`void`) `cb`, `mixed` ... `args`)`

        Description

          Verifies the mail address `addr` against the mail server.

          The callback will be called with

          - `cb(({ code, message }), @args);`

          where code and message are

          Array
          ``int` `code`` | The numerical return code from the VRFY call.
          ``string` `message`` | The textual answer to the VRFY call.

          or

          - `cb(({ 1, errno(), error_string, int(0..1) direct }), @args);`

          - `cb(({ 0, smtp-errorcode, error_string, int(0..1) direct }), @args);`

          with `direct` being `1` if this verify operation caused the error when the message can't be verified or when an error occurs.

        Note

          Some mail servers does not answer truthfully to verification queries in order to prevent spammers and others to gain information about the mail addresses present on the mail server.

      ## Class Protocols.SMTP.Client

        Description

          Synchronous (blocking) email class (this lets you send emails).

        Method create

          `Protocols.SMTP.Client Protocols.SMTP.Client()`
          `Protocols.SMTP.Client Protocols.SMTP.Client(`Stdio.File` `server`)`
          `Protocols.SMTP.Client Protocols.SMTP.Client(`string` `server`, `void`|`int` `port`)`

        Description

          Creates an SMTP mail client and connects it to the the `server` provided. The server parameter may either be a string with the hostname of the mail server, or it may be a file object acting as a mail server. If `server` is a string, then an optional port parameter may be provided. If no port parameter is provided, port 25 is assumed. If no parameters at all is provided the client will look up the mail host by searching for the DNS MX record.

        Throws

          Throws an exception if the client fails to connect to the mail server.

        Inherit ClientHelper

          `inherit ClientHelper : ClientHelper`

        Inherit Protocol

          `inherit Protocol : Protocol`

        Method send_message

          ``void` send_message(`string` `from`, `array`(`string`) `to`, `string` `body`)`

        Description

          Sends a mail message from `from` to the mail addresses listed in `to` with the mail body `body`. The body should be a correctly formatted mail DATA block, e.g. produced by `MIME.Message`.

        See also

          `simple_mail`

        Throws

          If the mail server returns any other return code than 200-399 an exception will be thrown.

        Method simple_mail

          ``void` simple_mail(`string` `to`, `string` `subject`, `string` `from`, `string` `msg`)`

        Description

          Sends an e-mail. Wrapper function that uses `send_message`.

        Note

          Some important headers are set to: `"Content-Type: text/plain; charset=iso-8859-1"` and `"Content-Transfer-Encoding: 8bit"`. The `"Date:"` header is set to the current local time. The `"Message-Id"` header is set to a `Standards.UUID` followed by the hostname as returned by `gethostname()`.

        Note

          If `gethostname()` is not supported, it will be replaced with the string `"localhost"`.

        Throws

          If the mail server returns any other return code than 200-399 an exception will be thrown.

        Method verify

          ``array`(`int`|`string`) verify(`string` `addr`)`

        Description

          Verifies the mail address `addr` against the mail server.

        Returns

          Array
          ``int` `code`` | The numerical return code from the VRFY call.
          ``string` `message`` | The textual answer to the VRFY call.

        Note

          Some mail servers does not answer truthfully to verification queries in order to prevent spammers and others to gain information about the mail addresses present on the mail server.

        Throws

          If the mail server returns any other return code than 200-399 an exception will be thrown.

      ## Class Protocols.SMTP.ClientHelper

        Description

          A helper class with functions useful when sending eMail.

        Method parse_addr

          ``protected` `string` parse_addr(`string` `addr`)`

        Description

          Parses email addresses as the `Protocols.SMTP` client classes do. Useful if emails should only be sent matching certain conditions etc..

        Method rfc2822date_time

          ``string` rfc2822date_time(`int` `ts`)`

        Description

          Return an RFC2822 date-time string suitable for the `Date:` header.

      ## Class Protocols.SMTP.Configuration

        Description

          Class to store configuration variable for the SMTP server

        Variable checkdns

          ``int` Protocols.SMTP.Configuration.checkdns`

        Description

          Verify sender domain for MX

        Variable checkemail

          ``int` Protocols.SMTP.Configuration.checkemail`

        Description

          Lamme check email from validity

        Variable givedata

          ``int` Protocols.SMTP.Configuration.givedata`

        Description

          Give raw data and normal MIME data, if set to yes your cb_data function should take an extra string argument

        Variable maxrcpt

          ``int` Protocols.SMTP.Configuration.maxrcpt`

        Description

          Maximum number of recipients (default 1000)

        Variable maxsize

          ``int` Protocols.SMTP.Configuration.maxsize`

        Description

          Message max size

      ## Class Protocols.SMTP.Connection

        Description

          The low-level class for the SMTP server

        Variable logfunction

          ``function`(`string`:`mixed`) Protocols.SMTP.Connection.logfunction`

        Description

          This function is called whenever the SMTP server logs something. By default the log function is `werror`.

      ## Class Protocols.SMTP.Server

        Description

          The use of Protocols.SMTP.server is quite easy and allow you to design custom functions to process mail. This module does not handle mail storage nor relaying to other domains. So it is your job to provide mail storage and relay mails to other servers

        Method create

          `Protocols.SMTP.Server Protocols.SMTP.Server(`array`(`string`) `_domains`, `void`|`int` `port`, `void`|`string` `ip`, `function`(:`void`) `_cb_mailfrom`, `function`(:`void`) `_cb_rcptto`, `function`(:`void`) `_cb_data`)`

        Description

          Create a receiving SMTP server. It implements RFC 2821, 2822 and 1854.

        Parameter `domain`

          Domains name this server relay, you need to provide at least one domain (the first one will be used for MAILER-DAEMON address). if you want to relay everything you can put a '*' after this first domain.

        Parameter `port`

          Port this server listen on

        Parameter `listenip`

          IP on which server listen

        Parameter `cb_mailfrom`

          Mailfrom callback function, this function will be called when a client send a mail from command. This function must take a string as argument (corresponding to the sender's email) and return int corresponding to the SMTP code to output to the client. If you return an array the first element is the SMTP code and the second is the error string to display.

        Parameter `cb_rcptto`

          Same as cb_mailfrom but called when a client sends a rcpt to.

        Parameter `cb_data`

          This function is called each time a client send a data content. It must have the following synopsis: int cb_data(object mime, string sender, array(string) recipients, void|string rawdata) object mime : the mime data object string sender : sender of the mail (from the mailfrom command) array(string) recipients : one or more recipients given by the rcpt to command return : SMTP code to output to the client. If you return an array the first element is the SMTP code and the second is the error string to display.

        Example

              Here is an example of silly program that does nothing except outputing
                informations to stdout.
               int cb_mailfrom(string mail)
               {
                 return 250;
               }
               int cb_rcptto(string email)
               {
                 // check the user's mailbox here
                 return 250;
               }
               int cb_data(object mime, string sender, array(string) recipients)
               {
                 write(sprintf("smtpd: mailfrom=%s, to=%s, headers=%O\ndata=%s\n",
                 sender, recipients * ", ", mime->headers, mime->getdata()));
                 // check the data and deliver the mail here
                 if(mime->body_parts)
                 {
                   foreach(mime->body_parts, object mpart)
                     write("smtpd: mpart data = %O\n", mpart->getdata());
                 }
                 return 250;
               }
               int main(int argc, array(string) argv)
               {
                 Protocols.SMTP.Server(({ "ece.fr" }), 2500, "127.0.0.1",       cb_mailfrom, cb_rcptto, cb_data);
                 return -1;
               }

    ## Module Protocols.SNMP

      Description

        SNMPv1 and v2c

      Constant ERROR_BADVALUE

        ``constant` Protocols.SNMP.`ERROR_BADVALUE``

      Description

        Error badValue

      Constant ERROR_GENERROR

        ``constant` Protocols.SNMP.`ERROR_GENERROR``

      Description

        Error genError

      Constant ERROR_NOERROR

        ``constant` Protocols.SNMP.`ERROR_NOERROR``

      Description

        Error noError

      Constant ERROR_NOSUCHNAME

        ``constant` Protocols.SNMP.`ERROR_NOSUCHNAME``

      Description

        Error noSuchName

      Constant ERROR_READONLY

        ``constant` Protocols.SNMP.`ERROR_READONLY``

      Description

        Error readOnly

      Constant ERROR_TOOBIG

        ``constant` Protocols.SNMP.`ERROR_TOOBIG``

      Description

        Error tooBig

      Constant REQUEST_GET

        ``constant` Protocols.SNMP.`REQUEST_GET``

      Description

        PDU type Get

      Constant REQUEST_GETNEXT

        ``constant` Protocols.SNMP.`REQUEST_GETNEXT``

      Description

        PDU type GetNext

      Constant REQUEST_GET_RESPONSE

        ``constant` Protocols.SNMP.`REQUEST_GET_RESPONSE``

      Description

        PDU type GetResponse

      Constant REQUEST_SET

        ``constant` Protocols.SNMP.`REQUEST_SET``

      Description

        PDU type Set

      Constant REQUEST_TRAP

        ``constant` Protocols.SNMP.`REQUEST_TRAP``

      Description

        PDU type Trap

      ## Class Protocols.SNMP.agent

        Description

          A simple SNMP agent with support for SNMP Get requests

        Method clear_get_oid_callback

          ``int` clear_get_oid_callback(`string` `oid`)`

        Description

          clear the Get callback function for an Object Identifier

        Parameter `oid`

          the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler.

        Returns

          1 if the callback existed, 0 otherwise

        Method clear_set_oid_callback

          ``int` clear_set_oid_callback(`string` `oid`)`

        Description

          clear the Set callback function for an Object Identifier

        Parameter `oid`

          the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler.

        Returns

          1 if the callback existed, 0 otherwise

        Method create

          `Protocols.SNMP.agent Protocols.SNMP.agent(`int`|`void` `port`, `string`|`void` `addr`)`

        Description

          create a new instance of the agent

        Parameter `port`

          the port number to listen for requests on

        Parameter `addr`

          the address to bind to for listening

        Note

          only one agent may be bound to a port at one time the agent does not currently support SMUX or AGENTX or other agent multiplexing protocols.

        Method get_get_oid_callback

          ``void`|`function`(:`void`) get_get_oid_callback(`string` `oid`)`

        Description

          get the Get request callback function for an Object Identifier

        Parameter `oid`

          the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler

        Returns

          the function associated with oid, if any

        Method get_set_oid_callback

          ``void`|`function`(:`void`) get_set_oid_callback(`string` `oid`)`

        Description

          get the Set request callback function for an Object Identifier

        Parameter `oid`

          the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler

        Returns

          the function associated with oid, if any

        Inherit "protocol"

          `inherit "protocol" : "protocol"`

        Method set_get_communities

          ``void` set_get_communities(`array` `communities`)`

        Description

          set the valid community strings for Get requests

        Parameter `communities`

          an array of valid Get communities

        Note

          send an empty array to disable Get requests

        Method set_get_oid_callback

          ``void` set_get_oid_callback(`string` `oid`, `function`(:`void`) `cb`)`

        Description

          set the Get request callback function for an Object Identifier

        Parameter `oid`

          the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to serve as the handler for all requests for which a handler is specified.

        Parameter `cb`

          the function to call when oid is requested by a manager the function should take 2 arguments: a string containing the requested oid and the body of the request as a mapping. The function should return an array containing 3 or 4 elements: The first is a boolean indicating success or failure. If success, the next 2 elements should be the SNMP data type of the result followed by the result itself. If failure, the next 2 elements should be the error-status such as `Protocols.SNMP.ERROR_TOOBIG` and the second is the error-index, if any. If a fourth array element is returned, it should contain the OID that the callback actually fetched (typically different from the requested OID for REQUEST_GETNEXT requests). This is needed for e.g. snmpwalk to work properly.

        Note

          there can be only one callback per object identifier. calling this function more than once with the same oid will result in the new callback replacing the existing one.

        Method set_managers

          ``void` set_managers(`array` `managers`)`

        Description

          set the valid manager list for requests

        Parameter `managers`

          an array of valid management hosts

        Note

          send an empty array to disable all requests

        Method set_managers_only

          ``void` set_managers_only(`int` `yesno`)`

        Description

          enable manager access limits

        Parameter `yesno`

          1 to allow only managers to submit requests 0 to allow any host to submit requests

          default setting allows all requests from all hosts

        Method set_set_communities

          ``void` set_set_communities(`array` `communities`)`

        Description

          set the valid community strings for Set requests

        Parameter `communities`

          an array of valid Set communities

        Note

          send an empty array to disable Set requests

        Method set_set_oid_callback

          ``void` set_set_oid_callback(`string` `oid`, `function`(:`void`) `cb`)`

        Description

          set the Set request callback function for an Object Identifier

        Parameter `oid`

          the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to serve as the handler for all requests for which a handler is specified.

        Parameter `cb`

          the function to call when oid is requested by a manager the function should take 3 arguments: a string containing the requested oid, the desired value, and the body of the request as a mapping. The function should return an array containing 3 elements: The first is a boolean indicating success or failure. If success, the next 2 elements should be the SNMP data type of the result followed by the result itself. If failure, the next 2 elements should be the error-status such as `Protocols.SNMP.ERROR_TOOBIG` and the second is the error-index, if any.

        Note

          there can be only one callback per object identifier. calling this function more than once with the same oid will result in the new callback replacing the existing one.

        Method set_threaded

          ``void` set_threaded()`

        Description

          Run the agent event loop in a thread, if available.

      ## Class Protocols.SNMP.protocol

        Description

          SNMP protocol implementation for Pike

          RFCs:

          implemented (yet): 1155-7 : v1

          1901-4 : v2/community (Bulk ops aren't implemented!)

          planned: 2742 : agentX

          2570 : v3 description

        Method create

          `Protocols.SNMP.protocol Protocols.SNMP.protocol(`int`|`void` `rem_port`, `string`|`void` `rem_addr`, `int`|`void` `loc_port`, `string`|`void` `loc_addr`)`

        Description

          create a new SNMP protocol object

        Parameter `rem_port`
        Parameter `rem_addr`

          remote address and UDP port (optional)

        Parameter `loc_port`
        Parameter `loc_addr`

          local address and UDP port (optional)

        Method decode_asn1_msg

          ``mapping` decode_asn1_msg(`mapping` `rawd`)`

        Description

          decode ASN1 data, if garbaged ignore it

        Method get_nextrequest

          ``int` get_nextrequest(`array`(`string`) `varlist`, `string`|`void` `rem_addr`, `int`|`void` `rem_port`)`

        Description

          GetNextRequest-PDU call

        Parameter `varlist`

          an array of OIDs to GET

        Parameter `rem_addr`
        Parameter `rem_port`

          remote address an UDP port to send request to (optional)

        Returns

          request ID

        Method get_request

          ``int` get_request(`array`(`string`) `varlist`, `string`|`void` `rem_addr`, `int`|`void` `rem_port`)`

        Description

          GetRequest-PDU call

        Parameter `varlist`

          an array of OIDs to GET

        Parameter `rem_addr`
        Parameter `rem_port`

          remote address an UDP port to send request to (optional)

        Returns

          request ID

        Method get_response

          ``int` get_response(`mapping` `varlist`, `mapping` `origdata`, `int`|`void` `errcode`, `int`|`void` `erridx`)`

        Description

          GetResponse-PDU call

        Parameter `varlist`

          a mapping containing data to return

          ``oid1` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oid1

          ``oid2` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oid2

          ``oidn` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oidn

        Parameter `origdata`

          original received decoded pdu that this response corresponds to

        Parameter `errcode`

          error code

        Parameter `erridx`

          error index

        Returns

          request ID

        Inherit snmp

          `inherit Stdio.UDP : snmp`

        Method readmsg

          ``mapping` readmsg(`int`|`float`|`void` `timeout`)`

        Description

          return the whole SNMP message in raw format

        Method readmsg_from_pool

          ``private` `mapping` readmsg_from_pool(`int` `msgid`)`

        Description

          read decoded message from pool

        Method set_request

          ``int` set_request(`mapping` `varlist`, `string`|`void` `rem_addr`, `int`|`void` `rem_port`)`

        Description

          SetRequest-PDU call

        Parameter `varlist`

          a mapping of OIDs to SET

          ``oid1` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oid1

          ``oid2` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oid2

          ``oidn` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oidn

        Parameter `rem_addr`
        Parameter `rem_port`

          remote address an UDP port to send request to (optional)

        Returns

          request ID

        Example

              // set the value of 1.3.6.1.4.1.1882.2.1 to "blah".
                 object s=Protocols.SNMP.protocol();
                 s->snmp_community="mysetcommunity";
                 mapping req=(["1.3.6.1.4.1.1882.2.1": ({"str", "blah"})]);
                 int id=s->set_request(req, "172.21.124.32");

        Variable snmp_community

          ``string` Protocols.SNMP.protocol.snmp_community`

        Description

          SNMP community string

          should be set to the appropriate SNMP community before sending a request.

        Note

          Set to "public" by default.

        Variable snmp_version

          ``int` Protocols.SNMP.protocol.snmp_version`

        Description

          SNMP version

          currently version 1 and 2 are supported.

        Method to_pool

          ``void` to_pool(`mapping` `rawd`)`

        Description

          decode raw pdu message and place in message pool

        Method trap

          ``int` trap(`mapping` `varlist`, `string` `oid`, `int` `type`, `int` `spectype`, `int` `ticks`, `string`|`void` `locip`, `string`|`void` `remaddr`, `int`|`void` `remport`)`

        Description

          send an SNMP-v1 trap

        Parameter `varlist`

          a mapping of OIDs to include in trap

          ``oid1` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oid1

          ``oid2` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oid2

          ``oidn` : `array``

          Array
          ``string` `type`` | data type such as tick, oid, gauge, etc
          ``mixed` `data`` | data to return for oidn

        Parameter `oid`
        Parameter `type`

          generic trap-type

        Parameter `spectype`

          specific trap-type

        Parameter `ticks`

          uptime

        Parameter `locip`

          originating ip address of the trap

        Parameter `remaddr`
        Parameter `remport`

          address and UDP to send trap to

        Returns

          request id

    ## Module Protocols.TELNET

      Description

        Implements TELNET as described by RFC 764 and RFC 854

        Also implements the Q method of TELNET option negotiation as specified by RFC 1143.

      Constant AUTH_WHO_CLIENT

        ``constant` `int` Protocols.TELNET.`AUTH_WHO_CLIENT``

      Description

        Client authenticating server

      Constant AUTH_WHO_SERVER

        ``constant` `int` Protocols.TELNET.`AUTH_WHO_SERVER``

      Description

        Server authenticating client

      Constant LFLOW_OFF

        ``constant` `int` Protocols.TELNET.`LFLOW_OFF``

      Description

        Disable remote flow control

      Constant LFLOW_ON

        ``constant` `int` Protocols.TELNET.`LFLOW_ON``

      Description

        Enable remote flow control

      Constant LFLOW_RESTART_ANY

        ``constant` `int` Protocols.TELNET.`LFLOW_RESTART_ANY``

      Description

        Restart output on any char

      Constant LFLOW_RESTART_XON

        ``constant` `int` Protocols.TELNET.`LFLOW_RESTART_XON``

      Description

        Restart output only on XON

      Constant TELQUAL_INFO

        ``constant` `int` Protocols.TELNET.`TELQUAL_INFO``

      Description

        ENVIRON: informational version of IS

      Constant TELQUAL_IS

        ``constant` `int` Protocols.TELNET.`TELQUAL_IS``

      Description

        option is...

      Constant TELQUAL_NAME

        ``constant` `int` Protocols.TELNET.`TELQUAL_NAME``

      Description

        AUTHENTICATION: client version of IS

      Constant TELQUAL_REPLY

        ``constant` `int` Protocols.TELNET.`TELQUAL_REPLY``

      Description

        AUTHENTICATION: client version of IS

      Constant TELQUAL_SEND

        ``constant` `int` Protocols.TELNET.`TELQUAL_SEND``

      Description

        send option

      Inherit TelnetCodes

        `inherit TelnetCodes : TelnetCodes`

      Inherit Telopts

        `inherit Telopts : Telopts`

      ## Class Protocols.TELNET.LineMode

        Description

          Line-oriented TELNET protocol handler.

        Inherit protocol

          `inherit protocol : protocol`

        Description

          Based on the generic TELNET protocol handler.

        Method setup

          ``protected` `void` setup()`

        Description

          Perform the initial TELNET handshaking for LINEMODE.

      ## Class Protocols.TELNET.Readline

        Description

          Line-oriented TELNET protocol handler with `Stdio.Readline` support.

          Implements the `Stdio.NonblockingStream` API.

        Method close

          ``void` close()`

        Description

          Close the connection.

        Method create

          `Protocols.TELNET.Readline Protocols.TELNET.Readline(`object` `f`, `function`(`mixed`, `string`:`void`) `r_cb`, `function`(`mixed`|`void`:`string`) `w_cb`, `function`(`mixed`|`void`:`void`) `c_cb`, `mapping` `callbacks`, `mixed`|`void` `new_id`)`

        Description

          Creates a TELNET protocol handler, and sets its callbacks.

        Parameter `f`

          File to use for the connection.

        Parameter `r_cb`

          Function to call when data has arrived.

        Parameter `w_cb`

          Function to call when the send buffer is empty.

        Parameter `c_cb`

          Function to call when the connection is closed.

        Parameter `callbacks`

          Mapping with callbacks for the various TELNET commands.

        Parameter `new_id`

          Value to send to the various callbacks.

        Inherit LineMode

          `inherit LineMode : LineMode`

        Description

          Based on the Line-oriented TELNET protocol handler.

        Method message

          ``void` message(`string` `s`, `void`|`int` `word_wrap`)`

        Description

          Write a message.

        Method query_close_callback

          ``function`(`mixed`|`void`:`void`) query_close_callback()`

        Method query_read_callback

          ``function`(`mixed`, `string`:`void`) query_read_callback()`

        Method query_write_callback

          ``function`(`mixed`|`void`:`string`) query_write_callback()`

        Variable readline

          ``Stdio.Readline` Protocols.TELNET.Readline.readline`

        Description

          `Stdio.Readline` object handling the connection.

        Method set_blocking

          ``void` set_blocking()`

        Method set_close_callback

          ``void` set_close_callback(`function`(`mixed`|`void`:`void`) `c_cb`)`

        Method set_nonblocking

          ``void` set_nonblocking(`function`(`mixed`, `string`:`void`) `r_cb`, `function`(`mixed`|`void`:`string`) `w_cb`, `function`(`mixed`|`void`:`void`) `c_cb`)`

        Description

          Change the asynchronous I/O callbacks.

        Parameter `r_cb`

          Function to call when data has arrived.

        Parameter `w_cb`

          Function to call when the send buffer is empty.

        Parameter `c_cb`

          Function to call when the connection is closed.

        See also

          `create()`

        Method set_prompt

          ``void` set_prompt(`string` `s`)`

        Description

          Set the readline prompt.

        Method set_read_callback

          ``void` set_read_callback(`function`(`mixed`, `string`:`void`) `r_cb`)`

        Method set_secret

          ``void` set_secret(`int` `onoff`)`

        Description

          Turn on/off echo mode.

        Method set_write_callback

          ``void` set_write_callback(`function`(`mixed`|`void`:`string`) `w_cb`)`

        Method tcgetattr

          ``mapping`(`string`:`int`) tcgetattr()`

        Description

          Get current terminal attributes.

          Currently only the following attributes are supported:

          ``"columns"`` | Number of columns.
          ``"rows"`` | Number of rows.
          ``"ECHO"`` | Local character echo on (`1`) or off (`0` (zero)).
          ``"ICANON"`` | Canonical input on (`1`) or off (`0` (zero)).

        Note

          Using this function currently bypasses the Readline layer.

        See also

          `Stdio.File()->tcgetattr()`

        Method tcsetattr

          ``int` tcsetattr(`mapping`(`string`:`int`) `options`, `string`|`void` `when`)`

        Description

          Set terminal attributes.

          Currently only the following attributes are supported:

          ``"ECHO"`` | Local character echo on (`1`) or off (`0` (zero)).
          ``"ICANON"`` | Canonical input on (`1`) or off (`0` (zero)).

        Note

          Using this function currently bypasses the Readline layer.

        See also

          `Stdio.File()->tcsetattr()`

        Method write

          ``void` write(`string` `s`)`

        Description

          Queues data to be sent to the other end of the connection.

        Parameter `s`

          String to send.

      ## Class Protocols.TELNET.TelnetCodes

        Description

          Table of IAC-codes.

        Constant ABORT

          ``constant` `int` Protocols.TELNET.TelnetCodes.`ABORT``

        Description

          Abort process

        Constant AO

          ``constant` `int` Protocols.TELNET.TelnetCodes.`AO``

        Description

          abort output--but let prog finish

        Constant AYT

          ``constant` `int` Protocols.TELNET.TelnetCodes.`AYT``

        Description

          are you there

        Constant BREAK

          ``constant` `int` Protocols.TELNET.TelnetCodes.`BREAK``

        Description

          break

        Constant DM

          ``constant` `int` Protocols.TELNET.TelnetCodes.`DM``

        Description

          data mark--for connect. cleaning

        Constant DO

          ``constant` `int` Protocols.TELNET.TelnetCodes.`DO``

        Description

          please, you use option

        Constant DONT

          ``constant` `int` Protocols.TELNET.TelnetCodes.`DONT``

        Description

          you are not to use option

        Constant EC

          ``constant` `int` Protocols.TELNET.TelnetCodes.`EC``

        Description

          erase the current character

        Constant EL

          ``constant` `int` Protocols.TELNET.TelnetCodes.`EL``

        Description

          erase the current line

        Constant EOR

          ``constant` `int` Protocols.TELNET.TelnetCodes.`EOR``

        Description

          end of record (transparent mode)

        Constant GA

          ``constant` `int` Protocols.TELNET.TelnetCodes.`GA``

        Description

          you may reverse the line

        Constant IAC

          ``constant` `int` Protocols.TELNET.TelnetCodes.`IAC``

        Description

          interpret as command.

        Constant IP

          ``constant` `int` Protocols.TELNET.TelnetCodes.`IP``

        Description

          interrupt process--permanently

        Constant NOP

          ``constant` `int` Protocols.TELNET.TelnetCodes.`NOP``

        Description

          nop

        Constant SB

          ``constant` `int` Protocols.TELNET.TelnetCodes.`SB``

        Description

          interpret as subnegotiation

        Constant SE

          ``constant` `int` Protocols.TELNET.TelnetCodes.`SE``

        Description

          end sub negotiation

        Constant SUSP

          ``constant` `int` Protocols.TELNET.TelnetCodes.`SUSP``

        Description

          Suspend process

        Constant SYNCH

          ``constant` `int` Protocols.TELNET.TelnetCodes.`SYNCH``

        Description

          for telfunc calls

        Constant WILL

          ``constant` `int` Protocols.TELNET.TelnetCodes.`WILL``

        Description

          I will use option

        Constant WONT

          ``constant` `int` Protocols.TELNET.TelnetCodes.`WONT``

        Description

          I won't use option

        Constant xEOF

          ``constant` `int` Protocols.TELNET.TelnetCodes.`xEOF``

        Description

          End of file: EOF is already used...

      ## Class Protocols.TELNET.Telopts

        Description

          Table of TELNET options.

        Constant TELOPT_3270REGIME

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_3270REGIME``

        Description

          3270 regime

        Constant TELOPT_AUTHENTICATION

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_AUTHENTICATION``

        Description

          Authenticate

        Constant TELOPT_BINARY

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_BINARY``

        Description

          8-bit data path

        Constant TELOPT_BM

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_BM``

        Description

          byte macro

        Constant TELOPT_DET

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_DET``

        Description

          data entry terminal

        Constant TELOPT_ECHO

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_ECHO``

        Description

          echo

        Constant TELOPT_ENCRYPT

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_ENCRYPT``

        Description

          Encryption option

        Constant TELOPT_EOR

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_EOR``

        Description

          end or record

        Constant TELOPT_EXOPL

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_EXOPL``

        Description

          extended-options-list

        Constant TELOPT_LFLOW

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_LFLOW``

        Description

          remote flow control

        Constant TELOPT_LINEMODE

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_LINEMODE``

        Description

          Linemode option

        Constant TELOPT_LOGOUT

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_LOGOUT``

        Description

          force logout

        Constant TELOPT_NAMS

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAMS``

        Description

          approximate message size

        Constant TELOPT_NAOCRD

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOCRD``

        Description

          negotiate about CR disposition

        Constant TELOPT_NAOFFD

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOFFD``

        Description

          negotiate about formfeed disposition

        Constant TELOPT_NAOHTD

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOHTD``

        Description

          negotiate about horizontal tab disposition

        Constant TELOPT_NAOHTS

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOHTS``

        Description

          negotiate about horizontal tabstops

        Constant TELOPT_NAOL

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOL``

        Description

          negotiate about output line width

        Constant TELOPT_NAOLFD

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOLFD``

        Description

          negotiate about output LF disposition

        Constant TELOPT_NAOP

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOP``

        Description

          negotiate about output page size

        Constant TELOPT_NAOVTD

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOVTD``

        Description

          negotiate about vertical tab disposition

        Constant TELOPT_NAOVTS

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAOVTS``

        Description

          negotiate about vertical tab stops

        Constant TELOPT_NAWS

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NAWS``

        Description

          window size

        Constant TELOPT_NEW_ENVIRON

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_NEW_ENVIRON``

        Description

          New - Environment variables

        Constant TELOPT_OLD_ENVIRON

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_OLD_ENVIRON``

        Description

          Old - Environment variables

        Constant TELOPT_OUTMRK

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_OUTMRK``

        Description

          output marking

        Constant TELOPT_RCP

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_RCP``

        Description

          prepare to reconnect

        Constant TELOPT_RCTE

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_RCTE``

        Description

          remote controlled transmission and echo

        Constant TELOPT_SGA

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_SGA``

        Description

          suppress go ahead

        Constant TELOPT_SNDLOC

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_SNDLOC``

        Description

          send location

        Constant TELOPT_STATUS

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_STATUS``

        Description

          give status

        Constant TELOPT_SUPDUP

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_SUPDUP``

        Description

          supdup protocol

        Constant TELOPT_SUPDUPOUTPUT

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_SUPDUPOUTPUT``

        Description

          supdup output

        Constant TELOPT_TM

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_TM``

        Description

          timing mark

        Constant TELOPT_TSPEED

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_TSPEED``

        Description

          terminal speed

        Constant TELOPT_TTYLOC

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_TTYLOC``

        Description

          terminal location number

        Constant TELOPT_TTYPE

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_TTYPE``

        Description

          terminal type

        Constant TELOPT_TUID

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_TUID``

        Description

          TACACS user identification

        Constant TELOPT_X3PAD

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_X3PAD``

        Description

          X.3 PAD

        Constant TELOPT_XASCII

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_XASCII``

        Description

          extended ascic character set

        Constant TELOPT_XDISPLOC

          ``constant` `int` Protocols.TELNET.Telopts.`TELOPT_XDISPLOC``

        Description

          X Display Location

      ## Class Protocols.TELNET.protocol

        Description

          Implementation of the TELNET protocol.

        Method call_read_cb

          ``protected` `void` call_read_cb(`string` `data`)`

        Description

          Calls `read_cb()`.

          Specifically provided for overloading

        Variable cb

          ``protected` `mapping` Protocols.TELNET.protocol.cb`

        Description

          Mapping containing extra callbacks.

        Method close

          ``void` close()`

        Description

          Closes the connetion neatly

        Variable close_cb

          ``protected` `function`(`mixed`|`void`:`void`) Protocols.TELNET.protocol.close_cb`

        Description

          Close callback.

        Method create

          `Protocols.TELNET.protocol Protocols.TELNET.protocol(`object` `f`, `function`(`mixed`, `string`:`void`) `r_cb`, `function`(`mixed`|`void`:`string`) `w_cb`, `function`(`mixed`|`void`:`void`) `c_cb`, `mapping` `callbacks`, `mixed`|`void` `new_id`)`

        Description

          Creates a TELNET protocol handler, and sets its callbacks.

        Parameter `f`

          File to use for the connection.

        Parameter `r_cb`

          Function to call when data has arrived.

        Parameter `w_cb`

          Function to call when the send buffer is empty.

        Parameter `c_cb`

          Function to call when the connection is closed.

        Parameter `callbacks`

          Mapping with callbacks for the various TELNET commands.

        Parameter `new_id`

          Value to send to the various callbacks.

        Method disable_write

          ``protected` `void` disable_write()`

        Description

          Turns off the write callback if apropriate.

        Variable done

          ``protected` `int` Protocols.TELNET.protocol.done`

        Description

          Indicates that connection should be closed

        Method enable_write

          ``protected` `void` enable_write()`

        Description

          Turns on the write callback if apropriate.

        Variable fd

          ``protected` `object` Protocols.TELNET.protocol.fd`

        Description

          The connection.

        Method got_data

          ``protected` `void` got_data(`mixed` `ignored`, `string` `line`)`

        Description

          Callback called when normal data has been received. This function also does most of the TELNET protocol parsing.

        Parameter `ignored`

          The id from the connection.

        Parameter `s`

          The received data.

        Method got_oob

          ``protected` `void` got_oob(`mixed` `ignored`, `string` `s`)`

        Description

          Callback called when Out-Of-Band data has been received.

        Parameter `ignored`

          The id from the connection.

        Parameter `s`

          The Out-Of-Band data received.

        Variable id

          ``protected` `mixed` Protocols.TELNET.protocol.id`

        Description

          Value to send to the callbacks.

        Variable remote_options
        Variable local_options

          ``protected` `array`(`int`) Protocols.TELNET.protocol.remote_options`
          ``protected` `array`(`int`) Protocols.TELNET.protocol.local_options`

        Description

          Negotiation states of all WILL/WON'T options. See RFC 1143 for a description of the states.

        Variable nonblocking_write

          ``protected` `int` Protocols.TELNET.protocol.nonblocking_write`

        Description

          Tells if we have set the nonblocking write callback or not.

        Method query_close_callback

          ``function`(`mixed`|`void`:`void`) query_close_callback()`

        Method query_read_callback

          ``function`(`mixed`, `string`:`void`) query_read_callback()`

        Method query_write_callback

          ``function`(`mixed`|`void`:`string`) query_write_callback()`

        Variable read_cb

          ``protected` `function`(`mixed`, `string`:`void`) Protocols.TELNET.protocol.read_cb`

        Description

          Read callback.

        Method send_DO

          ``void` send_DO(`int` `option`)`

        Description

          Starts negotiation to enable a TELNET option.

        Parameter `option`

          The option to enable.

        Method send_DONT

          ``void` send_DONT(`int` `option`)`

        Description

          Starts negotiation to disable a TELNET option.

        Parameter `option`

          The option to disable.

        Method send_data

          ``protected` `void` send_data()`

        Description

          Callback called when it is clear to send data over the connection. This function does the actual sending.

        Method send_synch

          ``void` send_synch()`

        Description

          Sends a TELNET synch command.

        Method set_close_callback

          ``void` set_close_callback(`function`(`mixed`|`void`:`void`) `c_cb`)`

        Method set_nonblocking

          ``void` set_nonblocking(`function`(`mixed`, `string`:`void`) `r_cb`, `function`(`mixed`|`void`:`string`) `w_cb`, `function`(`mixed`|`void`:`void`) `c_cb`)`

        Description

          Change the asynchronous I/O callbacks.

        Parameter `r_cb`

          Function to call when data has arrived.

        Parameter `w_cb`

          Function to call when the send buffer is empty.

        Parameter `c_cb`

          Function to call when the connection is closed.

        See also

          `create()`

        Method set_read_callback

          ``void` set_read_callback(`function`(`mixed`, `string`:`void`) `r_cb`)`

        Method set_write_callback

          ``void` set_write_callback(`function`(`mixed`|`void`:`string`) `w_cb`)`

        Description

          Sets the callback to be called when it is clear to send.

        Parameter `w_cb`

          The new write callback.

        Method setup

          ``protected` `void` setup()`

        Description

          Called when the initial setup is done.

          Created specifically for overloading

        Variable synch

          ``protected` `int` Protocols.TELNET.protocol.synch`

        Description

          Indicates whether we are in synch-mode or not.

        Variable to_send

          ``protected` `string` Protocols.TELNET.protocol.to_send`

        Description

          Data queued to be sent.

        Method write

          ``void` write(`string` `s`)`

        Description

          Queues data to be sent to the other end of the connection.

        Parameter `s`

          String to send.

        Variable write_cb

          ``protected` `function`(`mixed`|`void`:`string`) Protocols.TELNET.protocol.write_cb`

        Description

          Write callback.

        Method write_raw

          ``void` write_raw(`string` `s`)`

        Description

          Queues raw data to be sent to the other end of the connection.

        Parameter `s`

          String with raw telnet data to send.

    ## Module Protocols.WebSocket

      Description

        This module implements the WebSocket protocol as described in RFC 6455.

      ## Enum Protocols.WebSocket.CLOSE_STATUS

        Description

          WebSocket close status codes, as explained in the WebSocket protocol specification.

        Constant CLOSE_BAD_DATA

          ``constant` Protocols.WebSocket.`CLOSE_BAD_DATA``

        Constant CLOSE_BAD_TYPE

          ``constant` Protocols.WebSocket.`CLOSE_BAD_TYPE``

        Constant CLOSE_ERROR

          ``constant` Protocols.WebSocket.`CLOSE_ERROR``

        Constant CLOSE_EXTENSION

          ``constant` Protocols.WebSocket.`CLOSE_EXTENSION``

        Constant CLOSE_GONE_AWAY

          ``constant` Protocols.WebSocket.`CLOSE_GONE_AWAY``

        Constant CLOSE_NONE

          ``constant` Protocols.WebSocket.`CLOSE_NONE``

        Constant CLOSE_NORMAL

          ``constant` Protocols.WebSocket.`CLOSE_NORMAL``

        Constant CLOSE_POLICY

          ``constant` Protocols.WebSocket.`CLOSE_POLICY``

        Constant CLOSE_UNEXPECTED

          ``constant` Protocols.WebSocket.`CLOSE_UNEXPECTED``

      ## Enum Protocols.WebSocket.FRAME

        Description

          WebSocket frame opcodes.

        Constant FRAME_BINARY

          ``constant` Protocols.WebSocket.`FRAME_BINARY``

        Constant FRAME_CLOSE

          ``constant` Protocols.WebSocket.`FRAME_CLOSE``

        Constant FRAME_CONTINUATION

          ``constant` Protocols.WebSocket.`FRAME_CONTINUATION``

        Constant FRAME_PING

          ``constant` Protocols.WebSocket.`FRAME_PING``

        Constant FRAME_PONG

          ``constant` Protocols.WebSocket.`FRAME_PONG``

        Constant FRAME_TEXT

          ``constant` Protocols.WebSocket.`FRAME_TEXT``

      ## Class Protocols.WebSocket.Connection

        Variable buf

          ``Stdio.Buffer` Protocols.WebSocket.Connection.buf`

        Description

          Output buffer

        Variable bufferedAmount

          ``int` Protocols.WebSocket.Connection.bufferedAmount`

        Description

          Number of bytes in the send buffer.

        Method close

          ``void` close(`void`|`CLOSE_STATUS` `reason`)`

        Description

          Send a WebSocket connection close frame. The close callback will be called when the close handshake has been completed. No more frames can be sent after initiating the close handshake.

        Method connect

          ``int` connect(`Standards.URI` `endpoint`, `void`|`mapping`(`string`:`string`) `extra_headers`)`

        Description

          Connect to a remote WebSocket. This method will send the actual HTTP request to switch protocols to the server and once a HTTP 101 response is returned, switch the connection to WebSockets and call the `onopen` callback.

        Method create

          `Protocols.WebSocket.Connection Protocols.WebSocket.Connection()`

        Description

          Create a WebSocket client

        Method create

          `Protocols.WebSocket.Connection Protocols.WebSocket.Connection(`Stdio.File`|`SSL.File` `f`)`

        Description

          Create a WebSocket server out of the given Stdio.File-like object

        Variable endpoint

          ``Standards.URI` Protocols.WebSocket.Connection.endpoint`

        Description

          Remote endpoint in client mode

        Variable http_buffer

          ``protected` `Stdio.Buffer` Protocols.WebSocket.Connection.http_buffer`

        Description

          Used in client mode to read server response.

        Method http_read

          ``protected` `void` http_read(`mixed` `id`, `string` `data`)`

        Description

          Read callback for HTTP answer when we are in client mode and have requested an upgrade to WebSocket.

        Variable masking

          ``bool` Protocols.WebSocket.Connection.masking`

        Description

          If true, all outgoing frames are masked.

        Variable onclose

          ``function`(`CLOSE_STATUS`, `mixed`:`void`) Protocols.WebSocket.Connection.onclose`

        Description

          This callback will be called once the WebSocket has been closed. No more frames can be sent or will be received after the close event has been triggered. This happens either when receiving a frame initiating the close handshake or after the TCP connection has been closed. Note that this is a deviation from the WebSocket API specification.

        Variable onmessage

          ``function`(`Frame`, `mixed`:`void`) Protocols.WebSocket.Connection.onmessage`

        Variable onopen

          ``function`(`mixed`:`void`) Protocols.WebSocket.Connection.onopen`

        Variable parser

          ``Parser` Protocols.WebSocket.Connection.parser`

        Description

          An instance of `Parser` used to parse incoming data.

        Method ping

          ``void` ping(`void`|`string` `s`)`

        Description

          Send a WebSocket ping frame.

        Method request_upgrade

          ``protected` `void` request_upgrade()`

        Description

          Write callback during the upgrade of a socket.

        Method send

          ``void` send(`Frame` `frame`)`

        Description

          Send a WebSocket frame.

        Method send_binary

          ``void` send_binary(`string(8bit)` `s`)`

        Description

          Send a WebSocket binary frame.

        Method send_text

          ``void` send_text(`string` `s`)`

        Description

          Send a WebSocket text frame.

        Method set_id

          ``void` set_id(`mixed` `id`)`

        Description

          Set the `id`. It will be passed as last argument to all callbacks.

        Variable state

          ``STATE` Protocols.WebSocket.Connection.state`

        Variable stream

          ``Stdio.File`|`SSL.File` Protocols.WebSocket.Connection.stream`

        Description

          The actual client connection.

        ## Enum Protocols.WebSocket.Connection.STATE

          Constant CLOSED

            ``constant` Protocols.WebSocket.Connection.`CLOSED``

          Constant CLOSING

            ``constant` Protocols.WebSocket.Connection.`CLOSING``

          Constant CONNECTING

            ``constant` Protocols.WebSocket.Connection.`CONNECTING``

          Constant OPEN

            ``constant` Protocols.WebSocket.Connection.`OPEN``

      ## Class Protocols.WebSocket.Frame

        Method create

          `Protocols.WebSocket.Frame Protocols.WebSocket.Frame(`FRAME` `opcode`, `void`|`string`|`CLOSE_STATUS`)`
          `Protocols.WebSocket.Frame Protocols.WebSocket.Frame(`FRAME_TEXT`, `string` `text`)`
          `Protocols.WebSocket.Frame Protocols.WebSocket.Frame(`FRAME_BINARY`, `string(8bit)` `data`)`
          `Protocols.WebSocket.Frame Protocols.WebSocket.Frame(`FRAME_CLOSE`, `CLOSE_STATUS` `reason`)`
          `Protocols.WebSocket.Frame Protocols.WebSocket.Frame(`FRAME_PING`, `string(8bit)` `data`)`
          `Protocols.WebSocket.Frame Protocols.WebSocket.Frame(`FRAME_PONG`, `string(8bit)` `data`)`

        Variable data

          ``string` Protocols.WebSocket.Frame.data`

        Description

          Data part of the frame. Valid for frames of type `FRAME_BINARY`, `FRAME_PING` and `FRAME_PONG`.

        Method encode

          ``void` encode(`Stdio.Buffer` `buf`)`

        Variable fin

          ``bool` Protocols.WebSocket.Frame.fin`

        Description

          Set to `1` if this a final frame, i.e. the last frame of a fragmented message or a non-fragmentation frame.

        Variable opcode

          ``FRAME` Protocols.WebSocket.Frame.opcode`

        Variable reason

          ``CLOSE_STATUS` Protocols.WebSocket.Frame.reason`

        Description

          Only exists for frames of type `FRAME_CLOSE`.

        Variable text

          ``string` Protocols.WebSocket.Frame.text`

        Description

          Only exists for frames of type `FRAME_TEXT`.

      ## Class Protocols.WebSocket.Parser

        Description

          Parses WebSocket frames.

        Variable buf

          ``Stdio.Buffer` Protocols.WebSocket.Parser.buf`

        Description

          Unparsed data.

        Method feed

          ``void` feed(`string` `data`)`

        Description

          Add more data to the internal parsing buffer.

        Method parse

          ``Frame` parse()`

        Description

          Parses and returns one WebSocket frame from the internal buffer. If the buffer does not contain a full frame, `0` is returned.

      ## Class Protocols.WebSocket.Port

        Description

          Creates a simple HTTP Server. `ws_cb` will be called for all incoming WebSocket connections. Its first argument are the list of protocols requested by the client and the second argument the corresponding `Request` object. The WebSocket connection handshake is completed by calling `Request.websocket_accept`. `http_cb` will be called for all other HTTP Requests or if `ws_cb` is zero.

        See also

          `Protocols.HTTP.Server.Port`

        Inherit Port

          `inherit Protocols.HTTP.Server.Port : Port`

      ## Class Protocols.WebSocket.Request

        Variable cb

          ``function`(`array`(`string`), `Request`:`void`) Protocols.WebSocket.Request.cb`

        Method create

          `Protocols.WebSocket.Request Protocols.WebSocket.Request(`function`(`array`(`string`), `Request`:`void`) `cb`)`

        Inherit Request

          `inherit Protocols.HTTP.Server.Request : Request`

        Method websocket_accept

          ``Connection` websocket_accept(`string` `protocol`)`

        Description

          Calling `websocket_accept` completes the WebSocket connection handshake. The protocol should be either `0` or a protocol advertised by the client when initiating the WebSocket connection. The returned connection object is in state `Connection.OPEN`.

      ## Class Protocols.WebSocket.SSLPort

        Description

          Opens a simple HTTPS Server which supports WebSocket connections.

        See also

          `Port`, `Protocols.HTTP.Server.SSLPort`

        Inherit SSLPort

          `inherit Protocols.HTTP.Server.SSLPort : SSLPort`

    ## Module Protocols.X

      Description

        A Pike interface to the low-level X Window System.

        This implements the on-wire protocol and some simple useful abstractions.

      ## Module Protocols.X.Atom

        Description

          Keep track of X11 atoms

        ## Class Protocols.X.Atom.atom_manager

          Description

            Keeps track of known atoms. Is inherited into Xlib.Display

          Method InternAtom

            ``object` InternAtom(`string` `name`, `function`(:`void`)|`void` `callback`)`

          Description

            Looks up the atom in local cache. If it is not present, issue an asyncronous InternAtom request, and return 0

      ## Module Protocols.X.Extensions

        ## Class Protocols.X.Extensions.Extension

          Description

            an abstract class used to provide features for implimenting X11 extensions. Provides no useful functionality on its own.

          Method init

            ``int` init(`object` `d`)`

          Description

            initialize the extension.

          Parameter `d`

            An object of type Protocols.X.Xlib.Display

        ## Class Protocols.X.Extensions.ScreenSaver

          Inherit Extension

            `inherit Extension : Extension`

        ## Class Protocols.X.Extensions.Shape

          Method ShapeMask

            ``void` ShapeMask(`object` `window`, `int` `xo`, `int` `yo`, `string` `kind`, `string` `operation`, `object`|`void` `source`)`

          Method ShapeOffset

            ``void` ShapeOffset(`object` `window`, `string` `kind`, `int` `xo`, `int` `yo`)`

          Method ShapeRectangles

            ``void` ShapeRectangles(`object` `window`, `int` `xo`, `int` `yo`, `string` `kind`, `string` `operation`, `.Types.Rectangle`|`array`(`.Types.Rectangle`) `rectangles`)`

          Inherit Extension

            `inherit Extension : Extension`

        ## Class Protocols.X.Extensions.XTEST

          Description

            Provides support for the X11 XTEST extension.

          Method XTestFakeInput

            ``void` XTestFakeInput(`string` `event_type`, `int` `detail`, `int` `delay`, `object`|`void` `window`, `int`|`void` `xloc`, `int`|`void` `yloc`)`

          Description

            Send a synthetic event to an X server.

          Parameter `event_type`

            Type of event to send. Possible values: KeyPress: 2, KeyRelease: 3, ButtonPress: 4, ButtonRelease: 5, MotionNotify: 6

          Parameter `detail`

            Button (for Button events) or Keycode (for Key events) to send

          Parameter `delay`

            Delay before the X server simulates event. 0 indicates zero delay.

          Parameter `window`

            Window object that a motion event occurrs in. If no window is provided, the root window will be used.

          Parameter `xloc`

            For motion events, this is the relative X distance or absolute X coordinates.

          Parameter `yloc`

            For motion events, this is the relative Y distance or absolute Y coordinates.

          Method XTestGrabControl

            ``void` XTestGrabControl(`int` `impervious`)`

          Description

            Cause the executing client to become impervious to server grabs. That is, it can continue to execute requests even if another client grabs the server.

          Parameter `impervious`

            A true (non zero) value causes the client to perform as described above. If false (zero), server returns to the normal state of being susceptible to server grabs.

          Method create

            `Protocols.X.Extensions.XTEST Protocols.X.Extensions.XTEST()`

          Description

            Create object.

          Inherit Extension

            `inherit Extension : Extension`

          Method init

            ``int` init(`object` `display`)`

          Description

            Initialize the XTEST extension. Returns 1 if successful.

          Parameter `display`

            Protocols.X.Display object

      ## Module Protocols.X.KeySyms

        Method LookupCharacter

          ``int` LookupCharacter(`string` `str`)`

        Method LookupKeycode

          ``int` LookupKeycode(`int` `keysym`, `object` `display`)`

        Method LookupKeysym

          ``string` LookupKeysym(`int` `keysym`, `object` `display`)`

        Method ReleaseKey

          ``void` ReleaseKey(`int` `sym`)`

        Method _LookupCharacter

          ``int` _LookupCharacter(`string` `str`)`

        Method _LookupKeysym

          ``string` _LookupKeysym(`int` `keysym`)`

        Variable alt_gr
        Variable num_lock
        Variable shift
        Variable control
        Variable caps_lock
        Variable meta
        Variable alt
        Variable super
        Variable hyper

          ``int` Protocols.X.KeySyms.alt_gr`
          ``int` Protocols.X.KeySyms.num_lock`
          ``int` Protocols.X.KeySyms.shift`
          ``int` Protocols.X.KeySyms.control`
          ``int` Protocols.X.KeySyms.caps_lock`
          ``int` Protocols.X.KeySyms.meta`
          ``int` Protocols.X.KeySyms.alt`
          ``int` Protocols.X.KeySyms.super`
          ``int` Protocols.X.KeySyms.hyper`

        Variable attributes

          ``mapping` Protocols.X.KeySyms.attributes`

        Method makeKeysymtoKeycode

          ``void` makeKeysymtoKeycode(`object` `display`)`

        Variable stringtokeysyms

          ``mapping` Protocols.X.KeySyms.stringtokeysyms`

      ## Module Protocols.X.Requests

        Description

          Varios X11 on-wire requests

        ## Class Protocols.X.Requests.AllocColor

          Variable red
          Variable green
          Variable blue
          Variable colormap

            ``int` Protocols.X.Requests.AllocColor.red`
            ``int` Protocols.X.Requests.AllocColor.green`
            ``int` Protocols.X.Requests.AllocColor.blue`
            ``int` Protocols.X.Requests.AllocColor.colormap`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.Bell

          Inherit request

            `inherit request : request`

          Variable percent

            ``int` Protocols.X.Requests.Bell.percent`

        ## Class Protocols.X.Requests.ChangeGC

          Variable gc
          Variable attributes

            ``int` Protocols.X.Requests.ChangeGC.gc`
            ``mapping` Protocols.X.Requests.ChangeGC.attributes`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.ChangeProperty

          Variable mode
          Variable window
          Variable property
          Variable type
          Variable format
          Variable data

            ``int` Protocols.X.Requests.ChangeProperty.mode`
            ``int` Protocols.X.Requests.ChangeProperty.window`
            ``int` Protocols.X.Requests.ChangeProperty.property`
            ``int` Protocols.X.Requests.ChangeProperty.type`
            ``int` Protocols.X.Requests.ChangeProperty.format`
            ``string`|`array`(`int`) Protocols.X.Requests.ChangeProperty.data`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.ChangeWindowAttributes

          Variable window
          Variable attributes

            ``int` Protocols.X.Requests.ChangeWindowAttributes.window`
            ``mapping` Protocols.X.Requests.ChangeWindowAttributes.attributes`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.ClearArea

          Variable exposures
          Variable window
          Variable x
          Variable y
          Variable width
          Variable height

            ``int` Protocols.X.Requests.ClearArea.exposures`
            ``int` Protocols.X.Requests.ClearArea.window`
            ``int` Protocols.X.Requests.ClearArea.x`
            ``int` Protocols.X.Requests.ClearArea.y`
            ``int` Protocols.X.Requests.ClearArea.width`
            ``int` Protocols.X.Requests.ClearArea.height`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.CloseFont

          Inherit FreeRequest

            `inherit FreeRequest : FreeRequest`

        ## Class Protocols.X.Requests.ConfigureWindow

          Variable attributes

            ``mapping` Protocols.X.Requests.ConfigureWindow.attributes`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.CopyArea

          Variable gc
          Variable area
          Variable src
          Variable dst
          Variable x
          Variable y

            ``object` Protocols.X.Requests.CopyArea.gc`
            ``object` Protocols.X.Requests.CopyArea.area`
            ``object` Protocols.X.Requests.CopyArea.src`
            ``object` Protocols.X.Requests.CopyArea.dst`
            ``int` Protocols.X.Requests.CopyArea.x`
            ``int` Protocols.X.Requests.CopyArea.y`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.CopyPlane

          Inherit CopyArea

            `inherit CopyArea : CopyArea`

          Variable plane

            ``int` Protocols.X.Requests.CopyPlane.plane`

        ## Class Protocols.X.Requests.CreateColormap

          Variable cid
          Variable alloc

            ``int` Protocols.X.Requests.CreateColormap.cid`
            ``int` Protocols.X.Requests.CreateColormap.alloc`

          Inherit request

            `inherit request : request`

          Variable window
          Variable visual

            ``int` Protocols.X.Requests.CreateColormap.window`
            ``int` Protocols.X.Requests.CreateColormap.visual`

        ## Class Protocols.X.Requests.CreateGC

          Variable gc
          Variable drawable
          Variable attributes

            ``int` Protocols.X.Requests.CreateGC.gc`
            ``int` Protocols.X.Requests.CreateGC.drawable`
            ``mapping` Protocols.X.Requests.CreateGC.attributes`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.CreateGlyphCursor

          Variable cid
          Variable sourcefont
          Variable maskfont
          Variable sourcechar
          Variable maskchar
          Variable forered
          Variable foregreen
          Variable foreblue
          Variable backred
          Variable backgreen
          Variable backblue

            ``int` Protocols.X.Requests.CreateGlyphCursor.cid`
            ``int` Protocols.X.Requests.CreateGlyphCursor.sourcefont`
            ``int` Protocols.X.Requests.CreateGlyphCursor.maskfont`
            ``int` Protocols.X.Requests.CreateGlyphCursor.sourcechar`
            ``int` Protocols.X.Requests.CreateGlyphCursor.maskchar`
            ``int` Protocols.X.Requests.CreateGlyphCursor.forered`
            ``int` Protocols.X.Requests.CreateGlyphCursor.foregreen`
            ``int` Protocols.X.Requests.CreateGlyphCursor.foreblue`
            ``int` Protocols.X.Requests.CreateGlyphCursor.backred`
            ``int` Protocols.X.Requests.CreateGlyphCursor.backgreen`
            ``int` Protocols.X.Requests.CreateGlyphCursor.backblue`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.CreatePixmap

          Variable depth

            ``int` Protocols.X.Requests.CreatePixmap.depth`

          Variable pid
          Variable drawable

            ``int` Protocols.X.Requests.CreatePixmap.pid`
            ``int` Protocols.X.Requests.CreatePixmap.drawable`

          Variable width
          Variable height

            ``int` Protocols.X.Requests.CreatePixmap.width`
            ``int` Protocols.X.Requests.CreatePixmap.height`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.CreateWindow

          Variable attributes

            ``mapping` Protocols.X.Requests.CreateWindow.attributes`

          Variable x
          Variable y
          Variable width
          Variable height
          Variable borderWidth

            ``int` Protocols.X.Requests.CreateWindow.x`
            ``int` Protocols.X.Requests.CreateWindow.y`
            ``int` Protocols.X.Requests.CreateWindow.width`
            ``int` Protocols.X.Requests.CreateWindow.height`
            ``int` Protocols.X.Requests.CreateWindow.borderWidth`

          Variable c_class
          Variable visual

            ``int` Protocols.X.Requests.CreateWindow.c_class`
            ``int` Protocols.X.Requests.CreateWindow.visual`

          Variable depth

            ``int` Protocols.X.Requests.CreateWindow.depth`

          Inherit request

            `inherit request : request`

          Variable wid
          Variable parent

            ``int` Protocols.X.Requests.CreateWindow.wid`
            ``int` Protocols.X.Requests.CreateWindow.parent`

        ## Class Protocols.X.Requests.DeleteProperty

          Inherit request

            `inherit request : request`

          Variable window
          Variable property

            ``int` Protocols.X.Requests.DeleteProperty.window`
            ``int` Protocols.X.Requests.DeleteProperty.property`

        ## Class Protocols.X.Requests.ExtensionRequest

          Description

            Base class used by extensions

          Variable type
          Variable code
          Variable data
          Variable handle_reply
          Variable handle_error

            ``int` Protocols.X.Requests.ExtensionRequest.type`
            ``int` Protocols.X.Requests.ExtensionRequest.code`
            ``string` Protocols.X.Requests.ExtensionRequest.data`
            ``function`(:`void`) Protocols.X.Requests.ExtensionRequest.handle_reply`
            ``function`(:`void`) Protocols.X.Requests.ExtensionRequest.handle_error`

        ## Class Protocols.X.Requests.FillPoly

          Variable drawable
          Variable gc
          Variable shape
          Variable coordMode

            ``int` Protocols.X.Requests.FillPoly.drawable`
            ``int` Protocols.X.Requests.FillPoly.gc`
            ``int` Protocols.X.Requests.FillPoly.shape`
            ``int` Protocols.X.Requests.FillPoly.coordMode`

          Inherit request

            `inherit request : request`

          Variable points

            ``array` Protocols.X.Requests.FillPoly.points`

        ## Class Protocols.X.Requests.FreeColormap

          Inherit FreeRequest

            `inherit FreeRequest : FreeRequest`

        ## Class Protocols.X.Requests.FreeColors

          Variable colors
          Variable colormap
          Variable plane_mask

            ``array` Protocols.X.Requests.FreeColors.colors`
            ``int` Protocols.X.Requests.FreeColors.colormap`
            ``int` Protocols.X.Requests.FreeColors.plane_mask`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.FreeCursor

          Inherit FreeRequest

            `inherit FreeRequest : FreeRequest`

        ## Class Protocols.X.Requests.FreeGC

          Inherit FreeRequest

            `inherit FreeRequest : FreeRequest`

        ## Class Protocols.X.Requests.FreePixmap

          Inherit FreeRequest

            `inherit FreeRequest : FreeRequest`

        ## Class Protocols.X.Requests.FreeRequest

          Variable id

            ``int` Protocols.X.Requests.FreeRequest.id`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.GetAtomName

          Variable atom

            ``int` Protocols.X.Requests.GetAtomName.atom`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.GetKeyboardMapping

          Variable first
          Variable num

            ``int` Protocols.X.Requests.GetKeyboardMapping.first`
            ``int` Protocols.X.Requests.GetKeyboardMapping.num`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.GetProperty

          Variable delete
          Variable window
          Variable property
          Variable type
          Variable longOffset
          Variable longLength

            ``int` Protocols.X.Requests.GetProperty.delete`
            ``int` Protocols.X.Requests.GetProperty.window`
            ``int` Protocols.X.Requests.GetProperty.property`
            ``int` Protocols.X.Requests.GetProperty.type`
            ``int` Protocols.X.Requests.GetProperty.longOffset`
            ``int` Protocols.X.Requests.GetProperty.longLength`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.GrabButton

          Variable ownerEvents
          Variable grabWindow
          Variable eventMask
          Variable pointerMode
          Variable keyboardMode
          Variable confineTo
          Variable cursor
          Variable button
          Variable modifiers

            ``int` Protocols.X.Requests.GrabButton.ownerEvents`
            ``int` Protocols.X.Requests.GrabButton.grabWindow`
            ``int` Protocols.X.Requests.GrabButton.eventMask`
            ``int` Protocols.X.Requests.GrabButton.pointerMode`
            ``int` Protocols.X.Requests.GrabButton.keyboardMode`
            ``int` Protocols.X.Requests.GrabButton.confineTo`
            ``int` Protocols.X.Requests.GrabButton.cursor`
            ``int` Protocols.X.Requests.GrabButton.button`
            ``int` Protocols.X.Requests.GrabButton.modifiers`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.ImageText16

          Variable drawable
          Variable gc
          Variable x
          Variable y
          Variable str

            ``int` Protocols.X.Requests.ImageText16.drawable`
            ``int` Protocols.X.Requests.ImageText16.gc`
            ``int` Protocols.X.Requests.ImageText16.x`
            ``int` Protocols.X.Requests.ImageText16.y`
            ``string` Protocols.X.Requests.ImageText16.str`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.ImageText8

          Variable drawable
          Variable gc
          Variable x
          Variable y
          Variable str

            ``int` Protocols.X.Requests.ImageText8.drawable`
            ``int` Protocols.X.Requests.ImageText8.gc`
            ``int` Protocols.X.Requests.ImageText8.x`
            ``int` Protocols.X.Requests.ImageText8.y`
            ``string` Protocols.X.Requests.ImageText8.str`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.InternAtom

          Inherit request

            `inherit request : request`

          Variable onlyIfExists
          Variable name

            ``int` Protocols.X.Requests.InternAtom.onlyIfExists`
            ``string` Protocols.X.Requests.InternAtom.name`

        ## Class Protocols.X.Requests.ListProperties

          Inherit request

            `inherit request : request`

          Variable window

            ``int` Protocols.X.Requests.ListProperties.window`

        ## Class Protocols.X.Requests.MapWindow

          Inherit ResourceReq

            `inherit ResourceReq : ResourceReq`

        ## Class Protocols.X.Requests.OpenFont

          Variable fid
          Variable name

            ``int` Protocols.X.Requests.OpenFont.fid`
            ``string` Protocols.X.Requests.OpenFont.name`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.PolyFillRectangle

          Variable drawable
          Variable gc

            ``int` Protocols.X.Requests.PolyFillRectangle.drawable`
            ``int` Protocols.X.Requests.PolyFillRectangle.gc`

          Inherit request

            `inherit request : request`

          Variable rectangles

            ``array` Protocols.X.Requests.PolyFillRectangle.rectangles`

        ## Class Protocols.X.Requests.PolyLine

          Inherit PolyPoint

            `inherit PolyPoint : PolyPoint`

        ## Class Protocols.X.Requests.PolyPoint

          Variable coordMode
          Variable drawable
          Variable gc
          Variable points

            ``int` Protocols.X.Requests.PolyPoint.coordMode`
            ``int` Protocols.X.Requests.PolyPoint.drawable`
            ``int` Protocols.X.Requests.PolyPoint.gc`
            ``array`(`object`) Protocols.X.Requests.PolyPoint.points`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.PutImage

          Variable data

            ``string` Protocols.X.Requests.PutImage.data`

          Variable depth
          Variable width
          Variable height
          Variable dst_x
          Variable dst_y
          Variable left_pad
          Variable format

            ``int` Protocols.X.Requests.PutImage.depth`
            ``int` Protocols.X.Requests.PutImage.width`
            ``int` Protocols.X.Requests.PutImage.height`
            ``int` Protocols.X.Requests.PutImage.dst_x`
            ``int` Protocols.X.Requests.PutImage.dst_y`
            ``int` Protocols.X.Requests.PutImage.left_pad`
            ``int` Protocols.X.Requests.PutImage.format`

          Variable drawable
          Variable gc

            ``int` Protocols.X.Requests.PutImage.drawable`
            ``int` Protocols.X.Requests.PutImage.gc`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.QueryExtension

          Inherit request

            `inherit request : request`

          Variable name

            ``string` Protocols.X.Requests.QueryExtension.name`

        ## Class Protocols.X.Requests.QueryTextExtents

          Variable font
          Variable str

            ``int` Protocols.X.Requests.QueryTextExtents.font`
            ``string` Protocols.X.Requests.QueryTextExtents.str`

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.ResourceReq

          Inherit request

            `inherit request : request`

        ## Class Protocols.X.Requests.UnmapWindow

          Inherit ResourceReq

            `inherit ResourceReq : ResourceReq`

      ## Module Protocols.X.Types

        ## Class Protocols.X.Types.Colormap

          Method AllocColor

            ``int` AllocColor(`int` `r`, `int` `g`, `int` `b`)`

          Method FreeColor

            ``void` FreeColor(`int` `pixel`)`

          Variable visual
          Variable alloced

            ``object` Protocols.X.Types.Colormap.visual`
            ``mapping` Protocols.X.Types.Colormap.alloced`

          Inherit XResource

            `inherit XResource : XResource`

        ## Class Protocols.X.Types.Cursor

          Inherit XResource

            `inherit XResource : XResource`

        ## Class Protocols.X.Types.Drawable

          Method CopyArea

            ``object` CopyArea(`object` `gc`, `object` `src`, `object` `area`, `int` `x`, `int` `y`)`

          Method CopyArea_req

            ``object` CopyArea_req(`object` `gc`, `object` `src`, `object` `area`, `int` `x`, `int` `y`)`

          Method CreateGC

            ``object` CreateGC(`mapping`|`void` `attributes`)`

          Method CreateGC_req

            ``object` CreateGC_req()`

          Method CreatePixmap

            ``object` CreatePixmap(`int` `width`, `int` `height`, `int` `depth`)`

          Method CreatePixmap_req

            ``object` CreatePixmap_req(`int` `width`, `int` `height`, `int` `depth`)`

          Method DrawLine

            ``void` DrawLine(`object` `gc`, `int` `coordMode`, `object` ... `points`)`

          Method DrawLine_req

            ``object` DrawLine_req(`int` `gc`, `int` `coordMode`, `array`(`object`) `points`)`

          Method FillPoly

            ``void` FillPoly(`object` `gc`, `int` `shape`, `int` `coordMode`, `array`(`object`) `points`)`

          Method FillPoly_req

            ``object` FillPoly_req(`int` `gc`, `int` `shape`, `int` `coordMode`, `array`(`object`) `p`)`

          Method FillRectangles

            ``void` FillRectangles(`object` `gc`, `object` ... `r`)`

          Method FillRectangles_req

            ``object` FillRectangles_req(`int` `gc`, `array`(`object`) `r`)`

          Method ImageText16

            ``void` ImageText16(`object` `gc`, `int` `x`, `int` `y`, `string` `str`)`

          Method ImageText16_req

            ``object` ImageText16_req(`int` `gc`, `int` `x`, `int` `y`, `string` `str`)`

          Method ImageText8

            ``void` ImageText8(`object` `gc`, `int` `x`, `int` `y`, `string` `str`)`

          Method ImageText8_req

            ``object` ImageText8_req(`int` `gc`, `int` `x`, `int` `y`, `string` `str`)`

          Method PutImage

            ``void` PutImage(`object` `gc`, `int` `depth`, `int` `tx`, `int` `ty`, `int` `width`, `int` `height`, `string` `data`, `int`|`void` `format`)`

          Method PutImage_req

            ``object` PutImage_req(`object` `gc`, `int` `depth`, `int` `tx`, `int` `ty`, `int` `width`, `int` `height`, `string` `data`)`

          Inherit XResource

            `inherit XResource : XResource`

        ## Class Protocols.X.Types.Font

          Method CreateGlyphCursor

            ``object` CreateGlyphCursor(`int` `sourcechar`, `array`(`int`)|`void` `foreground`, `array`(`int`)|`void` `background`)`

          Method QueryTextExtents

            ``mapping`(`string`:`int`) QueryTextExtents(`string` `str`)`

          Method QueryTextExtents16

            ``mapping`(`string`:`int`) QueryTextExtents16(`string` `str`)`

          Method QueryTextExtents_req

            ``object` QueryTextExtents_req(`string` `str`)`

          Inherit XResource

            `inherit XResource : XResource`

        ## Class Protocols.X.Types.GC

          Method ChangeGC

            ``void` ChangeGC(`mapping` `attributes`)`

          Method ChangeGC_req

            ``object` ChangeGC_req(`mapping` `attributes`)`

          Method GetGCValues

            ``mapping`(`string`:`mixed`) GetGCValues()`

          Inherit XResource

            `inherit XResource : XResource`

          Variable values

            ``mapping`(`string`:`mixed`) Protocols.X.Types.GC.values`

        ## Class Protocols.X.Types.Pixmap

          Inherit Drawable

            `inherit Drawable : Drawable`

        ## Class Protocols.X.Types.Point

          Variable x
          Variable y

            ``int` Protocols.X.Types.Point.x`
            ``int` Protocols.X.Types.Point.y`

        ## Class Protocols.X.Types.Rectangle

          Variable width
          Variable height

            ``int` Protocols.X.Types.Rectangle.width`
            ``int` Protocols.X.Types.Rectangle.height`

          Variable x
          Variable y

            ``int` Protocols.X.Types.Rectangle.x`
            ``int` Protocols.X.Types.Rectangle.y`

        ## Class Protocols.X.Types.RootWindow

          Variable defaultColorMap
          Variable whitePixel
          Variable blackPixel
          Variable pixWidth
          Variable pixHeight
          Variable mmWidth
          Variable mmHeight
          Variable minInstalledMaps
          Variable maxInstalledMaps
          Variable backingStore
          Variable saveUnders
          Variable rootDepth
          Variable depths

            ``object` Protocols.X.Types.RootWindow.defaultColorMap`
            ``int` Protocols.X.Types.RootWindow.whitePixel`
            ``int` Protocols.X.Types.RootWindow.blackPixel`
            ``int` Protocols.X.Types.RootWindow.pixWidth`
            ``int` Protocols.X.Types.RootWindow.pixHeight`
            ``int` Protocols.X.Types.RootWindow.mmWidth`
            ``int` Protocols.X.Types.RootWindow.mmHeight`
            ``int` Protocols.X.Types.RootWindow.minInstalledMaps`
            ``int` Protocols.X.Types.RootWindow.maxInstalledMaps`
            ``int` Protocols.X.Types.RootWindow.backingStore`
            ``int` Protocols.X.Types.RootWindow.saveUnders`
            ``int` Protocols.X.Types.RootWindow.rootDepth`
            ``mapping` Protocols.X.Types.RootWindow.depths`

          Inherit Window

            `inherit Window : Window`

        ## Class Protocols.X.Types.Visual

          Variable c_class
          Variable bitsPerRGB
          Variable colorMapEntries
          Variable redMask
          Variable greenMask
          Variable blueMask

            ``int` Protocols.X.Types.Visual.c_class`
            ``int` Protocols.X.Types.Visual.bitsPerRGB`
            ``int` Protocols.X.Types.Visual.colorMapEntries`
            ``int` Protocols.X.Types.Visual.redMask`
            ``int` Protocols.X.Types.Visual.greenMask`
            ``int` Protocols.X.Types.Visual.blueMask`

          Variable depth

            ``int` Protocols.X.Types.Visual.depth`

          Inherit XResource

            `inherit XResource : XResource`

        ## Class Protocols.X.Types.Window

          Method ChangeAttributes

            ``void` ChangeAttributes(`mapping` `m`)`

          Method ChangeAttributes_req

            ``object` ChangeAttributes_req(`mapping` `m`)`

          Method ChangeProperty

            ``void` ChangeProperty(`object` `property`, `object` `type`, `int` `format`, `array`(`int`)|`string` `data`)`

          Method ChangeProperty_req

            ``object` ChangeProperty_req(`object` `property`, `object` `type`, `int` `format`, `array`(`int`)|`string` `data`)`

          Method ClearArea

            ``void` ClearArea(`int` `x`, `int` `y`, `int` `width`, `int` `height`, `int`|`void` `exposures`)`

          Method ClearArea_req

            ``object` ClearArea_req(`int` `x`, `int` `y`, `int` `width`, `int` `height`, `int` `exposures`)`

          Method Configure

            ``void` Configure(`mapping` `m`)`

          Method Configure_req

            ``object` Configure_req(`mapping` `m`)`

          Method CreateColormap

            ``object` CreateColormap(`object` `visual`, `int`|`void` `alloc`)`

          Method CreateSimpleWindow

            ``object` CreateSimpleWindow(`int` `x`, `int` `y`, `int` `width`, `int` `height`, `int` `border_width`, `int` `border`, `int` `background`)`

          Method CreateWindow

            ``object` CreateWindow(`int` `x`, `int` `y`, `int` `width`, `int` `height`, `int` `border_width`, `mapping`|`void` `attributes`, `object`|`void` `visual`, `int`|`void` `d`, `int`|`void` `c_class`)`

          Method CreateWindow_req

            ``object` CreateWindow_req(`int` `x`, `int` `y`, `int` `width`, `int` `height`, `int` `border_width`, `int` `depth`, `object` `visual`)`

          Method DeselectInput

            ``int` DeselectInput(`string` ... `types`)`

          Method GetProperty

            ``mapping` GetProperty(`object` `property`, `object`|`void` `type`)`

          Method GetProperty_req

            ``object` GetProperty_req(`object` `property`, `object`|`void` `type`)`

          Method GrabButton

            ``void` GrabButton(`int` `button`, `int` `modifiers`, `string` ... `types`)`

          Method GrabButton_req

            ``object` GrabButton_req(`int` `button`, `int` `modifiers`, `array`(`string`) `types`)`

          Method ListProperties

            ``array` ListProperties()`

          Method ListProperties_req

            ``object` ListProperties_req()`

          Method Lower

            ``void` Lower()`

          Method Map

            ``void` Map()`

          Method Map_req

            ``object` Map_req()`

          Method Raise

            ``void` Raise()`

          Method SelectInput

            ``int` SelectInput(`string` ... `types`)`

          Method SelectInput_req

            ``object` SelectInput_req()`

          Method ShapeMask

            ``void` ShapeMask(`string` `kind`, `int` `xo`, `int` `yo`, `string` `operation`, `Pixmap` `mask`)`

          Method ShapeOffset

            ``void` ShapeOffset(`string` `kind`, `int` `xo`, `int` `yo`)`

          Method ShapeRectangles

            ``void` ShapeRectangles(`string` `kind`, `int` `xo`, `int` `yo`, `string` `operation`, `array`(`Rectangle`) `rectangles`)`

          Method Unmap

            ``void` Unmap()`

          Method Unmap_req

            ``object` Unmap_req()`

          Variable currentInputMask

            ``int` Protocols.X.Types.Window.currentInputMask`

          Variable event_callbacks

            ``mapping`(`string`:`array`(`array`)) Protocols.X.Types.Window.event_callbacks`

          Inherit Drawable

            `inherit Drawable : Drawable`

          Inherit KeySyms

            `inherit .KeySyms : KeySyms`

          Method set_event_callback

            ``void` set_event_callback(`string` `type`, `function`(:`void`) `f`, `int`|`void` `priority`)`

        ## Class Protocols.X.Types.XResource

          Description

            A resorce in the X-server Most will automatically free the resource in the server when all references is gone in your application

          Method Free

            ``void` Free()`

          Variable display
          Variable id
          Variable autofree

            ``object` Protocols.X.Types.XResource.display`
            ``int` Protocols.X.Types.XResource.id`
            ``int` Protocols.X.Types.XResource.autofree`

      ## Module Protocols.X.XImage

        Description

          Handles Image.Image to XImage conversions.

          The `XImage` class behaves more or less exactly like an Image.Image, but it keeps itself synchronized with the server if so needed.

        Method MakeShapeMask

          ``object` MakeShapeMask(`object` `in`, `object` `alpha`)`

        Description

          Convert an alpha channel to a shaped-window extension mask

        Method ShapedWindowImage

          ``void` ShapedWindowImage(`object` `in`, `object` `color`, `object`|`void` `alpha`, `int`|`void` `contour`)`

        Description

          Make the window `in` display the image, with a mask shaped according to alpha, and optionally with a colored border aound the mask.

        ## Class Protocols.X.XImage.Image_wrapper

          Description

            Wrapper for Image.Image that keeps track of the modifications done.

        ## Class Protocols.X.XImage.PixmapImage

          Description

            A pixmap (much like XImage, but stored in the server)

          Inherit XImage

            `inherit XImage : XImage`

        ## Class Protocols.X.XImage.WindowImage

          Description

            A version of XImage that redraws itself at need

          Inherit XImage

            `inherit XImage : XImage`

        ## Class Protocols.X.XImage.XImage

          Method allocate_colortable

            ``Image.Colortable` allocate_colortable()`

          Variable best

            ``int` Protocols.X.XImage.XImage.best`

          Variable depth
          Variable bpp
          Variable converter
          Variable linepad
          Variable swapbytes
          Variable rmask
          Variable gmask
          Variable bmask

            ``int` Protocols.X.XImage.XImage.depth`
            ``int` Protocols.X.XImage.XImage.bpp`
            ``function`(:`void`) Protocols.X.XImage.XImage.converter`
            ``int` Protocols.X.XImage.XImage.linepad`
            ``int` Protocols.X.XImage.XImage.swapbytes`
            ``int` Protocols.X.XImage.XImage.rmask`
            ``int` Protocols.X.XImage.XImage.gmask`
            ``int` Protocols.X.XImage.XImage.bmask`

          Variable window
          Variable root
          Variable visual
          Variable colormap
          Variable ccol
          Variable dgc

            ``object` Protocols.X.XImage.XImage.window`
            ``object` Protocols.X.XImage.XImage.root`
            ``object` Protocols.X.XImage.XImage.visual`
            ``object` Protocols.X.XImage.XImage.colormap`
            ``Image.Colortable` Protocols.X.XImage.XImage.ccol`
            ``object` Protocols.X.XImage.XImage.dgc`

          Inherit Image_wrapper

            `inherit Image_wrapper : Image_wrapper`

          Variable offset_x
          Variable offset_y

            ``int` Protocols.X.XImage.XImage.offset_x`
            ``int` Protocols.X.XImage.XImage.offset_y`

          Method redraw

            ``void` redraw(`int` `x`, `int` `y`, `int` `width`, `int` `height`)`

          Method set_drawable

            ``void` set_drawable(`object` `w`)`

          Method set_offset

            ``void` set_offset(`int` `x`, `int` `y`)`

          Method set_window

            ``void` set_window(`object` `w`)`

      ## Module Protocols.X.XTools

        Description

          Various tools that are higher level than raw X, but are lower level than widgets.

        ## Class Protocols.X.XTools.Button

          Description

            A simple button. Steals and processes mousebutton events Can be inherited and then expanded the button_pressed function

          Variable pressed
          Variable inside
          Variable button

            ``int` Protocols.X.XTools.Button.pressed`
            ``int` Protocols.X.XTools.Button.inside`
            ``int` Protocols.X.XTools.Button.button`

          Method button_exposed

            ``void` button_exposed(`mapping` `event`)`

          Method button_pressed

            ``mapping` button_pressed(`mapping` `event`)`

          Method button_released

            ``mapping` button_released(`mapping` `event`)`

          Method create

            `Protocols.X.XTools.Button Protocols.X.XTools.Button(`object` `w`, `int`|`void` `b`)`

          Method window_entered

            ``mapping` window_entered(`mapping` `event`)`

          Method window_left

            ``mapping` window_left(`mapping` `event`)`

      ## Module Protocols.X.Xlib

        Description

          Implementations of various X11 calls.

        ## Class Protocols.X.Xlib.Display

          Description

            The representation of a X display.

            Keeps the connection to the X server and various other information needed to use X11.

          Method Bell

            ``void` Bell(`int` `volume`)`

          Method Bell_req

            ``object` Bell_req(`int` `volume`)`

          Method CreateGlyphCursor

            ``object` CreateGlyphCursor(`object` `sourcefont`, `int` `sourcechar`, `object`|`void` `maskfont`, `int`|`void` `maskchar`, `array`(`int`)|`void` `foreground`, `array`(`int`)|`void` `background`)`

          Method CreateGlyphCursor_req

            ``object` CreateGlyphCursor_req(`object` `sourcefont`, `object` `maskfont`, `int` `sourcechar`, `int` `maskchar`, `array`(`int`) `foreground`, `array`(`int`) `background`)`

          Method DefaultRootWindow

            ``object` DefaultRootWindow()`

          Method OpenFont

            ``object` OpenFont(`string` `name`)`

          Method OpenFont_req

            ``object` OpenFont_req(`string` `name`)`

          Variable imageByteOrder
          Variable bitmapBitOrder

            ``int` Protocols.X.Xlib.Display.imageByteOrder`
            ``int` Protocols.X.Xlib.Display.bitmapBitOrder`

          Variable bitmapScanlineUnit
          Variable bitmapScanlinePad

            ``int` Protocols.X.Xlib.Display.bitmapScanlineUnit`
            ``int` Protocols.X.Xlib.Display.bitmapScanlinePad`

          Method blocking_request

            ``array` blocking_request(`.Requests.request` `req`)`

          Variable extensions

            ``mapping`(`string`:`.Extensions.Extension`) Protocols.X.Xlib.Display.extensions`

          Description

            All extensions supported by the server and this module

          Variable formats

            ``array` Protocols.X.Xlib.Display.formats`

          Inherit File

            `inherit Stdio.File : File`

          Inherit atom_manager

            `inherit .Atom.atom_manager : atom_manager`

          Inherit id_manager

            `inherit id_manager : id_manager`

          Variable key_mapping

            ``array` Protocols.X.Xlib.Display.key_mapping`

          Variable majorVersion
          Variable minorVersion

            ``int` Protocols.X.Xlib.Display.majorVersion`
            ``int` Protocols.X.Xlib.Display.minorVersion`

          Description

            The protocol major and minor version reported by the server

          Variable minKeyCode
          Variable maxKeyCode

            ``int` Protocols.X.Xlib.Display.minKeyCode`
            ``int` Protocols.X.Xlib.Display.maxKeyCode`

          Variable maxRequestSize

            ``int` Protocols.X.Xlib.Display.maxRequestSize`

          Variable motionBufferSize

            ``int` Protocols.X.Xlib.Display.motionBufferSize`

          Method open

            ``int` open(`string`|`void` `display`)`

          Description

            Connect to the specified display. The default is to use the value of the environment variable DISPLAY

          Variable release

            ``int` Protocols.X.Xlib.Display.release`

          Description

            Server release number

          Variable roots

            ``array` Protocols.X.Xlib.Display.roots`

          Variable screen_number

            ``int` Protocols.X.Xlib.Display.screen_number`

          Method send_async_request

            ``void` send_async_request(`.Requests.request` `req`, `function`(:`void`) `callback`)`

          Variable vendor

            ``string` Protocols.X.Xlib.Display.vendor`

    ## Module Protocols.XMLRPC

      Description

        This module implements most features of the XML-RPC standard (see http://xml-rpc.org/).

        Translation rules for conversions from Pike datatypes to XML-RPC datatypes:

        Pike `int` is translated to XML-RPC `<int>`. Pike `string` is translated to XML-RPC `<string>`. Pike `float` is translated to XML-RPC `<double>`. Pike `mapping` is translated to XML-RPC `<struct>`. Pike `array` is translated to XML-RPC `<array>`. Pike `Calendar` object is translated to XML-RPC `<dateTime.iso8601`. Pike `Val.false` and `Val.true` is translated to XML-RPC `<boolean>`.

        Translation rules for conversions from XML-RPC datatypes to Pike datatypes:

        XML-RPC `<i4>` and `<int>` are translated to Pike `int`. XML-RPC `<boolean>` is translated to Pike `Val.true` and `Val.false`. XML-RPC `<string>` and `<base64>` are translated to Pike `string`. XML_RPC `<double>` is translated to Pike `float`. XML-RPC `<struct>` is translated to Pike `mapping`. XML-RPC `<array>` is translated to Pike `array`. XML-RPC `<dateTime.iso8601>` is translated to Pike `Calendar` object.

      Note

        The XML-RPC `<dateTime.iso8601>` datatype does not assume any time zone, but local time is always used in the conversion to `Calendar` objects.

      Method decode_call

        ``Call` decode_call(`string` `xml_input`)`

      Description

        Decodes a XML-RPC representation of a function call and returns a `Call` object.

      See also

        `Call`

      Method decode_response

        ``array`|`Fault` decode_response(`string` `xml_input`, `int`|`void` `boolean`)`

      Description

        Decodes a XML-RPC representation of a response and returns an array containing response values, or a `Fault` object.

      See also

        `Fault`

      Method encode_call

        ``string` encode_call(`string` `method_name`, `array` `params`)`

      Description

        Encodes a function call with the name `method_name` and the arguments `params` and returns the XML-RPC string representation.

      Method encode_response

        ``string` encode_response(`array` `params`)`

      Description

        Encodes a response containing the multiple values in `params` and returns the XML-RPC string representation.

      Method encode_response_fault

        ``string` encode_response_fault(`int` `fault_code`, `string` `fault_string`)`

      Description

        Encodes a response fault containing a `fault_code` and a `fault_string` and returns the XML-RPC string representation.

      ## Class Protocols.XMLRPC.AsyncClient

        Description

          This class implements an XML-RPC client that uses HTTP transport using non blocking sockets.

          There is an optional boolean flag to get the new behavior of booleans being returned Val instead of ints.

        Example

              void data_ok(mixed result)
              {
                write("result=%O\n", result);
              }

              void fail()
              {
                write("fail\n");
              }

              int main(int argc, array argv)
              {
                object async_client = Protocols.XMLRPC.AsyncClient("http://www.oreillynet.com/meerkat/xml-rpc/server.php");
                async_client["system.listMethods"](data_ok, fail);
                return -1;

      ## Class Protocols.XMLRPC.Call

        Description

          Represents a function call made to a XML-RPC server.

        See also

          `decode_call()`

        Method create

          `Protocols.XMLRPC.Call Protocols.XMLRPC.Call(`string` `method_name`, `array` `params`)`

        Variable method_name

          ``int` Protocols.XMLRPC.Call.method_name`

        Description

          Represents `<methodName>` in the XML-RPC standard.

        Variable method_name
        Variable params

          ``string` Protocols.XMLRPC.Call.method_name`
          ``array` Protocols.XMLRPC.Call.params`

        Variable params

          ``array` Protocols.XMLRPC.Call.params`

        Description

          Represents `<params>` in the XML-RPC standard where all datatypes have been converted to equivalent or similar datatypes in Pike.

      ## Class Protocols.XMLRPC.Client

        Description

          This class implements an XML-RPC client that uses HTTP transport.

          There is an optional boolean flag to get the new behavior of booleans being returned as Val instead of ints.

        Example

                 > Protocols.XMLRPC.Client client = Protocols.XMLRPC.Client("http://www.oreillynet.com/meerkat/xml-rpc/server.php");
                 Result: Protocols.XMLRPC.Client("http://www.oreillynet.com/meerkat/xml-rpc/server.php");
                 > client["system.listMethods"]();
                 Result: ({ /* 1 element */
                		    ({ /* 9 elements */
                			"meerkat.getChannels",
                			"meerkat.getCategories",
                			"meerkat.getCategoriesBySubstring",
                			"meerkat.getChannelsByCategory",
                			"meerkat.getChannelsBySubstring",
                			"meerkat.getItems",
                			"system.listMethods",
                			"system.methodHelp",
                			"system.methodSignature"
                		    })
                		})

        Variable url
        Variable boolean

          ``string`|`Standards.URI` Protocols.XMLRPC.Client.url`
          ``int`|`void` Protocols.XMLRPC.Client.boolean`

        Method create

          `Protocols.XMLRPC.Client Protocols.XMLRPC.Client(`string`|`Standards.URI` `url`, `int`|`void` `boolean`)`

      ## Class Protocols.XMLRPC.Fault

        Description

          Represents a fault response which can be one of the return values from a XML-RPC function call.

        See also

          `decode_response()`

        Method create

          `Protocols.XMLRPC.Fault Protocols.XMLRPC.Fault(`int` `fault_code`, `string` `fault_string`)`

        Variable fault_code

          ``int` Protocols.XMLRPC.Fault.fault_code`

        Description

          Represents `faultCode` in the XML-RPC standard.

        Variable fault_code
        Variable fault_string

          ``int` Protocols.XMLRPC.Fault.fault_code`
          ``string` Protocols.XMLRPC.Fault.fault_string`

        Variable fault_string

          ``int` Protocols.XMLRPC.Fault.fault_string`

        Description

          Represents `faultString` in the XML-RPC standard.