13. Protocols

Module Protocols.HTTP


Methoddelete_url

.Querydelete_url(string|Standards.URIurl, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon)

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.


Methoddo_async_method

voiddo_async_method(stringmethod, string|Standards.URIurl, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, Protocols.HTTP.Querycon, void|stringdata)

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


Methoddo_async_proxied_method

voiddo_async_proxied_method(string|Standards.URIproxy, stringuser, stringpassword, stringmethod, string|Standards.URIurl, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, Protocols.HTTP.Querycon, void|stringdata)

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


Methoddo_method

.Querydo_method(stringmethod, string|Standards.URIurl, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon, void|stringdata)

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


Methoddo_proxied_method

.Querydo_proxied_method(string|Standards.URIproxy, stringuser, stringpassword, stringmethod, string|Standards.URIurl, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon, void|stringdata)

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


Methodget_url

.Queryget_url(string|Standards.URIurl, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon)

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.


Methodget_url_data

stringget_url_data(string|Standards.URIurl, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon)

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.


Methodget_url_nice

array(string) get_url_nice(string|Standards.URIurl, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon)

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.


Methodhttp_encode_cookie

__deprecated__stringhttp_encode_cookie(stringf)

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

Methodhttp_encode_query

stringhttp_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( (["&":"&","'=\"":"\0\0\0"]) );  
     Result: "%26amp%3b=%26&%27%3d%22=%00%00%00"
	

Methodhttp_encode_string

__deprecated__stringhttp_encode_string(stringin)

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.


Methodiri_encode

stringiri_encode(strings)

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


Methodiri_normalize

stringiri_normalize(strings)

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


Methodpercent_decode

stringpercent_decode(strings)

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.


Methodpercent_encode

stringpercent_encode(strings)

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.


Methodpost_url

.Querypost_url(string|Standards.URIurl, mapping(string:int|string|array(string))|stringquery_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon)

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.


Methodpost_url_data

stringpost_url_data(string|Standards.URIurl, mapping(string:int|string|array(string))|stringquery_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon)

Description

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


Methodpost_url_nice

array(string) post_url_nice(string|Standards.URIurl, mapping(string:int|string|array(string))|stringquery_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon)

Description

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


Methodput_url

.Queryput_url(string|Standards.URIurl, void|stringfile, void|mapping(string:int|string|array(string)) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Querycon)

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.


Methodquoted_string_decode

stringquoted_string_decode(strings)

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


Methodquoted_string_encode

stringquoted_string_encode(strings)

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


Methodunentity

__deprecated__stringunentity(strings)

Description

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

Deprecated

Replaced by Parser.parse_html_entities.


Methoduri_decode

stringuri_decode(strings)

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


Methoduri_encode

stringuri_encode(strings)

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


Methoduri_encode_invalids

stringuri_encode_invalids(strings)

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


Methoduri_normalize

stringuri_normalize(strings)

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.


Methodasync_fetch

voidasync_fetch(function(:void) callback, mixed ... extra)

Description

Fetch all data in background.

See also

timed_async_fetch(), async_request(), set_callbacks()


Methodset_callbacks
Methodasync_request

Protocols.HTTP.Queryset_callbacks(function(:void) request_ok, function(:void) request_fail, mixed ... extra)
Protocols.HTTP.Queryasync_request(stringserver, intport, stringquery)
Protocols.HTTP.Queryasync_request(stringserver, intport, stringquery, mappingheaders, string|voiddata)

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


Methodcast

(array)Protocols.HTTP.Query()

Returns
Array
mapping0

Headers

string1

Data

string2

Protocol

int3

Status

string4

Status description


Methodcast

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


Methodcast

(string)Protocols.HTTP.Query()

Description

Gives back the answer as a string.


Methodclose

voidclose()

Description

Close all associated file descriptors.


Methoddata

stringdata(int|voidmax_length)

Description

Gives back the data as a string.


Methoddatafile

Protocols.HTTP.Query.PseudoFiledatafile()

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


Methoddownloaded_bytes

intdownloaded_bytes()

Description

Gives back the number of downloaded bytes.


Variableerrno

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.


Methodfile

Protocols.HTTP.Query.PseudoFilefile()
Protocols.HTTP.Query.PseudoFilefile(mappingnewheaders, void|mappingremoveheaders)

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


Variableheaders

mapping Protocols.HTTP.Query.headers

Description

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


Variablehost
Variablereal_host
Variableport

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.


Variablehostname_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().


Variableok

int Protocols.HTTP.Query.ok

Description

Tells if the connection is successfull.


Variableprotocol

string Protocols.HTTP.Query.protocol

Description

Protocol string, ie "HTTP/1.0".


Variablestatus
Variablestatus_desc

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

Description

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


Methodthread_request

Protocols.HTTP.Querythread_request(stringserver, intport, stringquery)
Protocols.HTTP.Querythread_request(stringserver, intport, stringquery, mappingheaders, void|stringdata)

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.


Methodtimed_async_fetch

voidtimed_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()


Methodtotal_bytes

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


Methodunicode_data

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


Methodclose

voidclose()


Methodread

stringread(intn, bool|voidnot_all)

Class Protocols.HTTP.Session


Methodasync_get_url
Methodasync_put_url
Methodasync_delete_url
Methodasync_post_url

Requestasync_get_url(URLurl, void|mappingquery_variables, function(:void) callback_headers_ok, function(:void) callback_data_ok, function(:void) callback_fail, mixed ... callback_arguments)
Requestasync_put_url(URLurl, void|stringfile, void|mappingquery_variables, function(:void) callback_headers_ok, function(:void) callback_data_ok, function(:void) callback_fail, mixed ... callback_arguments)
Requestasync_delete_url(URLurl, void|mappingquery_variables, function(:void) callback_headers_ok, function(:void) callback_data_ok, function(:void) callback_fail, mixed ... callback_arguments)
Requestasync_post_url(URLurl, mappingquery_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.


Methodencode_cookies
Methoddecode_cookies

stringencode_cookies()
voiddecode_cookies(stringdata, voidno_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.


Variabledefault_headers

mapping Protocols.HTTP.Session.default_headers

Description

Default HTTP headers.


Methodget_url
Methodpost_url
Methodput_url
Methoddelete_url

Requestget_url(URLurl, void|mappingquery_variables)
Requestpost_url(URLurl, mapping|stringquery_variables)
Requestput_url(URLurl, stringfile, void|mappingquery_variables)
Requestdelete_url(URLurl, void|mappingquery_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.


Variablefollow_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


Methodget_cookies

array(string) get_cookies(Standards.URI|SessionURLfor_url, void|boolno_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.


Methodget_url_nice
Methodget_url_data
Methodpost_url_nice
Methodpost_url_data

array(string) get_url_nice(URLurl, mappingquery_variables)
stringget_url_data(URLurl, mappingquery_variables)
array(string) post_url_nice(URLurl, mapping|stringquery_variables)
stringpost_url_data(URLurl, mapping|stringquery_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.


Methodgive_me_connection

Querygive_me_connection(Standards.URIurl)

Description

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


Variablehostname_cache

mapping Protocols.HTTP.Session.hostname_cache

Description

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


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


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


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


Methodreturn_connection

voidreturn_connection(Standards.URIurl, Queryquery)

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.


Methodset_cookie

voidset_cookie(Cookiecookie, Standards.URIwho)

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.


Methodset_http_cookie

voidset_http_cookie(stringcookie, Standards.URIat)

Description

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


Variabletime_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


Variablecon

Query Protocols.HTTP.Session.Request.con

Description

Raw connection object


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


Methoddestroy

voiddestroy()

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.


Methoddo_async

Requestdo_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


Methoddo_sync

Requestdo_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


Methoddo_thread

Requestdo_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


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


Methodprepare_method

array(string|int|mapping) prepare_method(stringmethod, URLurl, void|mappingquery_variables, void|mappingextra_headers, void|stringdata)

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


Methodset_callbacks

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


Variableurl_requested

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

Description

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


Methodwait

Requestwait()

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


Methodcreate

Protocols.HTTP.Session.SessionURLProtocols.HTTP.Session.SessionURL(URLuri, URLbase_uri, URL_referer)

Description

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


InheritURI

inherit Standards.URI : URI


Variablereferer

URL Protocols.HTTP.Session.SessionURL.referer

Description

the referer to this URL

Module Protocols.HTTP.Server


ConstantHeaderParser

constant Protocols.HTTP.Server.HeaderParser

Description

Fast HTTP header parser.


Methodextension_to_type

stringextension_to_type(stringextension)

Description

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


Methodfilename_to_type

stringfilename_to_type(stringfilename)

Description

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


Methodhttp_date

stringhttp_date(inttime)

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


Methodhttp_decode_date

inthttp_decode_date(stringdata)

Description

Decode a HTTP date to seconds since 1970 (UTC)

Returns

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


Constanthttp_decode_string

constant Protocols.HTTP.Server.http_decode_string


Methodhttp_decode_urlencoded_query

mapping(string:string|array(string)) http_decode_urlencoded_query(stringquery, void|mappingdest)

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.


Methodclose

voidclose()

Description

Closes the HTTP port.


Methodcreate

Protocols.HTTP.Server.PortProtocols.HTTP.Server.Port(function(.Request:void) callback)
Protocols.HTTP.Server.PortProtocols.HTTP.Server.Port(function(.Request:void) callback, intportno, void|stringinterface)


Variablerequest_program

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

Class Protocols.HTTP.Server.Request


Variablebody_raw

string Protocols.HTTP.Server.Request.body_raw

Description

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


Variableconnection_timeout_delay

int Protocols.HTTP.Server.Request.connection_timeout_delay

Description

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


Variablecookies

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

Description

cookies set by client


Variablefull_query

string Protocols.HTTP.Server.Request.full_query

Description

full resource requested, including attached GET query


Methodget_ip

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


Variablemisc

mapping Protocols.HTTP.Server.Request.misc

Description

external use only


Variablemy_fd

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

Description

The socket that this request came in on.


Variablenot_query

string Protocols.HTTP.Server.Request.not_query

Description

resource requested minus any attached query


Variableprotocol

string Protocols.HTTP.Server.Request.protocol

Description

request protocol and version, eg. HTTP/1.0


Variablequery

string Protocols.HTTP.Server.Request.query

Description

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


Variableraw

string Protocols.HTTP.Server.Request.raw

Description

raw unparsed full request (headers and body)


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


Variablerequest_raw

string Protocols.HTTP.Server.Request.request_raw

Description

full request line (request_type + full_query + protocol)


Variablerequest_type

string Protocols.HTTP.Server.Request.request_type

Description

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


Methodresponse_and_finish

voidresponse_and_finish(mappingm, 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.


Variablesend_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


Methodsent_data

intsent_data()

Description

Returns the amount of data sent.


Variablevariables

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.


Methodcreate

Protocols.HTTP.Server.SSLPortProtocols.HTTP.Server.SSLPort(function(Request:void) callback, void|intport, void|stringinterface, void|string|Crypto.Sign.Statekey, void|string|array(string) certificate, void|intshare)

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


InheritPort

inherit SSL.Port : Port


Methodnew_connection

protectedvoidnew_connection()

Description

The port accept callback


Variablerequest_program

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


Methodset_certificate

__deprecated__voidset_certificate(string|array(string) certificate)

Deprecated

Replaced by add_cert.


Methodset_key

__deprecated__voidset_key(stringskey)

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.


Methodcreate

SSL.AlertSSL.Alert(int(1..2)level, int(8bit)description, ProtocolVersionversion, string|voidmessage)


InheritPacket

inherit .Packet : Packet

Description

Based on the base Packet.

Class SSL.ClientConnection

Description

Client-side connection state.


Variableclient_cert_types
Variableclient_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.


Methodclient_hello

Packetclient_hello(string(8bit)|voidserver_name)


Methodcreate

SSL.ClientConnectionSSL.ClientConnection(Contextctx, string(8bit)|voidserver_name, Session|voidsession)

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.


Methodhandle_handshake

int(-1..1)handle_handshake(inttype, 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.


InheritConnection

inherit Connection : Connection


Methodsend_renegotiate

voidsend_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 States: 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


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


Variableclient_random
Variableserver_random

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

Description

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


Methodcreate

SSL.ConnectionSSL.Connection(Contextctx)

Description

Initialize the connection state.

Parameter ctx

The context for the connection.


Methoddescribe_state

stringdescribe_state()

Description

Returns a string describing the current connection state.


Methodgot_data

string(8bit)|intgot_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.


Methodhandle_handshake

int(-1..1)handle_handshake(inttype, 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.


Variableke

.Cipher.KeyExchange SSL.Connection.ke

Description

The active Cipher.KeyExchange (if any).


Methodquery_write_queue_size

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


Methodrecv_packet

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


Methodsend_close

voidsend_close()

Description

Initiate close.


Methodsend_packet

voidsend_packet(Packetpacket, int|voidpriority)

Description

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


Methodsend_renegotiate

voidsend_renegotiate()

Description

Renegotiate the connection.


Methodsend_streaming_data

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


Variablesent

int SSL.Connection.sent

Description

Number of application data bytes sent by us.


Methodset_alert_callback

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


Variablestate

ConnectionState SSL.Connection.state

Description

Bitfield with the current connection state.


Methodto_write

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


Methodadd_cert

voidadd_cert(Crypto.Sign.Statekey, array(string(8bit)) certs, array(string(8bit))|voidextra_name_globs)
variantvoidadd_cert(string(8bit)key, array(string(8bit)) certs, array(string(8bit))|voidextra_name_globs)
variantvoidadd_cert(CertificatePaircp)

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


Variableadvertised_protocols

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

Description

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


Methodalert_factory

Alertalert_factory(SSL.Connectioncon, intlevel, intdescription, ProtocolVersionversion, string|voidmessage, mixed|voidtrace)

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.


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


Variablecertificates

__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()


Variableclient_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()


Variableclient_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()


Methodconfigure_suite_b

voidconfigure_suite_b(int(128..)|voidmin_keylength, int(0..)|voidstrictness_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()


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


Methoddhe_dss_mode

__deprecated__voiddhe_dss_mode(int(0..)|voidmin_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.


Variabledsa

__deprecated__Crypto.DSA.State SSL.Context.dsa

Description

Getting

Compatibility.

Deprecated

Replaced by find_cert.

Setting

Compatibility.

Deprecated

Replaced by find_cert.


Variableecc_curves

array(int) SSL.Context.ecc_curves

Description

Supported elliptical curve cipher curves in order of preference.


Variableencrypt_then_mac

int SSL.Context.encrypt_then_mac

Description

Attempt to enable encrypt-then-mac mode.


Methodfilter_weak_suites

voidfilter_weak_suites(intmin_keylength)

Description

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


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


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


Methodget_authorities

array(string) get_authorities()

Description

Get the list of allowed authorities. See set_authorities.


Methodget_certificates

array(CertificatePair) get_certificates()

Description

Returns a list of all server certificates added with add_cert.


Methodget_signature_algorithms

array(array(int)) get_signature_algorithms(array(array(int))|voidsignature_algorithms)

Description

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

See also

signature_algorithms


Methodget_suites

array(int) get_suites(int(-1..)|voidmin_keylength, int(0..2)|voidke_flags, multiset(int)|voidblacklisted_ciphers, multiset(KeyExchangeType)|voidblacklisted_kes, multiset(HashAlgorithm)|voidblacklisted_hashes, multiset(CipherModes)|voidblacklisted_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.


Methodget_trusted_issuers

array(array(string)) get_trusted_issuers()

Description

Get the list of trusted issuers. See set_trusted_issuers.


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


Variablelong_rsa
Variableshort_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.


Variablelong_rsa_counter
Variableshort_rsa_counter

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

Description

Counters for export RSA keys.


Methodlookup_session

Sessionlookup_session(stringid)

Description

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


Variablemax_sessions

int SSL.Context.max_sessions

Description

Maximum number of sessions to keep in the cache.


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


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


Methodnew_session

Sessionnew_session()

Description

Create a new session.


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


Variablepreferred_auth_methods

array(int) SSL.Context.preferred_auth_methods

Description

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


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


Variablepreferred_suites

array(int) SSL.Context.preferred_suites

Description

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


Methodpurge_session

voidpurge_session(Sessions)

Description

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


Variablerandom

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.


Methodrecord_session

voidrecord_session(Sessions)

Description

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


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


Variablersa

__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()


Methodrsa_mode

__deprecated__voidrsa_mode(int(0..)|voidmin_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.


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


Methodset_authorities

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


Methodset_trusted_issuers

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


Variablesignature_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()


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


Variableuse_cache

int SSL.Context.use_cache

Description

Non-zero to enable caching of sessions


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


Methodaccept

boolaccept(string|voidpending_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()


Variableapplication_protocol

string SSL.File.application_protocol

Description

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

Note

Read only


Methodbackend_once

protectedint(0..0)|floatbackend_once(int|voidnonwaiting_mode)

Description

Run one pass of the backend.


Methodclose

intclose(void|stringhow, void|intclean_close, void|intdont_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


Methodconnect

SSL.Sessionconnect(string|voiddest_addr, SSL.Session|voidsession)

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


Methodcreate

SSL.FileSSL.File(Stdio.Filestream, SSL.Contextctx)

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


Methoddestroy

protectedvoiddestroy()

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


Methoderrno

interrno()

Returns

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

0

No error

System.EPIPE

Connection closed by other end.


Variablefragment_max_size

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


Methodget_peer_certificate_info

mappingget_peer_certificate_info()

Returns

Returns peer certificate information, if any.


Methodget_peer_certificates

arrayget_peer_certificates()

Returns

Returns the peer certificate chain, if any.


Methodinternal_poll

protectedvoidinternal_poll()

Description

Check whether any callbacks may need to be called.

Always run via the real_backend.

See also

schedule_poll()


Methodis_open

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


Methodlinger

boollinger(int(-1..65535)|voidseconds)

Description

Set the linger time on close().


Methodquery_accept_callback

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

Returns

Returns the current accept callback.

See also

set_accept_callback


Methodquery_address

stringquery_address(int|voidarg)

Returns

Returns the address and port of the connection.

See Stdio.File.query_address for details.

See also

Stdio.File.query_address


Methodquery_alert_callback

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

Returns

Returns the current alert callback.

See also

set_alert_callback


Methodquery_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


Methodquery_backend

Pike.Backendquery_backend()

Description

Return the backend used for the file callbacks.

See also

set_backend


Methodquery_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


Methodquery_close_callback

function(void|mixed:int) query_close_callback()

Returns

Returns the current close callback.

See also

set_close_callback, set_nonblocking, query_callbacks


Methodquery_connection

.Connectionquery_connection()

Description

Return the SSL connection object.

This returns the low-level SSL.connection object.


Methodquery_context

SSL.Contextquery_context()

Description

Return the SSL context object.


Methodquery_id

mixedquery_id()

Returns

Returns the currently set id.

See also

set_id


Methodquery_read_callback

function(void|mixed, void|string:int) query_read_callback()

Returns

Returns the current read callback.

See also

set_read_callback, set_nonblocking, query_callbacks


Methodquery_stream

Stdio.Filequery_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


Methodquery_suite

intquery_suite()

Description

Return the currently active cipher suite.


Methodquery_version

ProtocolVersionquery_version()

Description

Return the currently active SSL/TLS version.


Methodquery_write_callback

function(void|mixed:int) query_write_callback()

Returns

Returns the current write callback.

See also

set_write_callback, set_nonblocking, query_callbacks


Methodread

stringread(void|intlength, void|boolnot_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


Methodrenegotiate

intrenegotiate()

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.


Methodschedule_poll

protectedvoidschedule_poll()

Description

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

See also

internal_poll()


Methodset_accept_callback

voidset_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


Methodset_alert_callback

voidset_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


Methodset_backend

voidset_backend(Pike.Backendbackend)

Description

Set the backend used for the file callbacks.

See also

query_backend


Methodset_blocking

voidset_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


Methodset_blocking_keep_callbacks

voidset_blocking_keep_callbacks()

Description

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

See also

set_blocking, set_nonblocking


Methodset_callbacks

voidset_callbacks(void|function(mixed, string:int) read, void|function(mixed:int) 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


Methodset_close_callback

voidset_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


Methodset_id

voidset_id(mixedid)

Description

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

See also

query_id


Methodset_nonblocking

voidset_nonblocking(void|function(void|mixed, void|string:int) read, void|function(void|mixed:int) 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


Methodset_nonblocking_keep_callbacks

voidset_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


Methodset_read_callback

voidset_read_callback(function(void|mixed, void|string:int) read)

Description

Install a function to be called when data is available.

See also

query_read_callback, set_nonblocking, query_callbacks


Methodset_write_callback

voidset_write_callback(function(void|mixed:int) write)

Description

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

See also

query_write_callback, set_nonblocking, query_callbacks


Methodshutdown

Stdio.Fileshutdown()

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


Methodwrite

intwrite(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.


Methodcreate

SSL.PacketSSL.Packet(ProtocolVersionversion, void|intextra)

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.


Methodrecv

string(8bit)|.Packetrecv(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.


Methodsend

stringsend()

Description

Serialize the packet for sending.

Returns

Returns the serialized packet.

Class SSL.Port

Description

Interface similar to Stdio.Port.


Methodaccept

Fileaccept()

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.


Variableaccept_callback

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


Methodbind

intbind(intport, function(SSL.File|void, mixed|void:int) callback, string|voidip, int|voidshare)

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 Files 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()


Methodcreate

SSL.PortSSL.Port(Context|voidctx)

Description

Create a new port for accepting SSL connections.

See also

bind(), listen_fd()


Variablectx

Context SSL.Port.ctx

Description

Context to use for the connections.


Methodfinished_callback

voidfinished_callback(SSL.Filef, mixed|voidid)

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 Files on the accept queue.

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


Inheritsocket

inherit Stdio.Port : socket


Methodlisten_fd

intlisten_fd(intfd, 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 Files 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()


Methodsocket_accept

Stdio.Filesocket_accept()

Description

Low-level accept.

See also

Stdio.Port()->accept()


Methodssl_callback

voidssl_callback(mixedid)

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.


Methodhandle_handshake

int(-1..1)handle_handshake(inttype, 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.


InheritConnection

inherit Connection : Connection


Methodsend_renegotiate

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


Variablecert_data

mapping SSL.Session.cert_data

Description

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


Variablecertificate_chain

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

Description

our certificate chain


Variablecipher_spec

Cipher.CipherSpec SSL.Session.cipher_spec

Description

Information about the encryption method derived from the cipher_suite.


Variablecipher_suite

int SSL.Session.cipher_suite

Description

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


Variablecompression_algorithm

int SSL.Session.compression_algorithm

Description

Always COMPRESSION_null.


Variablecurve

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

Variableecc_curves

array(int) SSL.Session.ecc_curves

Description

Supported elliptical curve cipher curves in order of preference.


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


Variableencrypt_then_mac

int SSL.Session.encrypt_then_mac

Description

Negotiated encrypt-then-mac mode.


Methodgenerate_keys

array(string(8bit)) generate_keys(string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

Description

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

Returns
Array
string0

Client write MAC secret

string1

Server write MAC secret

string2

Client write key

string3

Server write key

string4

Client write IV

string5

Server write IV


Methodhas_required_certificates

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


Variableheartbeat_mode

HeartBeatModeType SSL.Session.heartbeat_mode

Description

Heartbeat mode.


Variableidentity

string(8bit) SSL.Session.identity

Description

Identifies the session to the server


Methodis_supported_cert

protectedboolis_supported_cert(CertificatePaircp, intke_mask, inth_max, ProtocolVersionversion, 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.


Methodis_supported_suite

boolis_supported_suite(intsuite, intke_mask, ProtocolVersionversion)

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.


Variablemaster_secret

string(8bit) SSL.Session.master_secret

Description

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


Variablemax_packet_size

int SSL.Session.max_packet_size

Description

The max fragment size requested by the client.


Methodnew_client_states

array(State) new_client_states(.Connectioncon, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

Description

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

Returns
Array
SSL.Stateread_state

Read state

SSL.Statewrite_state

Write state


Methodnew_server_states

array(State) new_server_states(.Connectioncon, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

Description

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

Returns
Array
SSL.Stateread_state

Read state

SSL.Statewrite_state

Write state


Variablepeer_certificate_chain

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

Description

the peer certificate chain


Variablepeer_public_key

Crypto.Sign.State SSL.Session.peer_public_key

Description

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


Variableprivate_key

Crypto.Sign.State SSL.Session.private_key

Description

Our private key.


Methodreusable_as

boolreusable_as(Sessionother)

Description

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


Methodselect_cipher_suite

intselect_cipher_suite(array(CertificatePair) certs, array(int) cipher_suites, ProtocolVersionversion)

Description

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

Parameter certs

The list of CertificatePairs 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.


Variableserver_name

string(8bit) SSL.Session.server_name

Description

RFC 6066 3.1 (SNI)


Methodset_cipher_suite

intset_cipher_suite(intsuite, ProtocolVersionversion, array(array(int)) signature_algorithms, intmax_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

Methodset_compression_method

voidset_compression_method(intcompr)

Description

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


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


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


Variableversion

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.


Variablecrypt

Cipher.CipherAlgorithm SSL.State.crypt

Description

Encryption or decryption object.


Methoddecrypt_packet

Alert|Packetdecrypt_packet(Packetpacket)

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.


Methodencrypt_packet

Alert|Packetencrypt_packet(Packetpacket)

Description

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


Variablemac

Cipher.MACAlgorithm SSL.State.mac

Description

Message Authentication Code


Variablesalt

string SSL.State.salt

Description

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


Variableseq_num

int SSL.State.seq_num

Description

64-bit sequence number.


Variablesession

Session SSL.State.session

Description

Information about the used algorithms.


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


MethodP_hash

protectedstring(8bit)P_hash(Crypto.Hashhashfn, string(8bit)secret, string(8bit)seed, intlen)

Description

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


Methodlookup

CipherSpeclookup(intsuite, ProtocolVersion|intversion, array(array(int)) signature_algorithms, intmax_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.


Methodprf_sha384

string(8bit)prf_sha384(string(8bit)secret, string(8bit)label, string(8bit)seed, intlen)

Description

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


Methodprf_sha512

string(8bit)prf_sha512(string(8bit)secret, string(8bit)label, string(8bit)seed, intlen)

Description

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


Methodprf_ssl_3_0

string(8bit)prf_ssl_3_0(string(8bit)secret, string(8bit)label, string(8bit)seed, intlen)

Description

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

Note

The argument label is ignored.


Methodprf_tls_1_0

string(8bit)prf_tls_1_0(string(8bit)secret, string(8bit)label, string(8bit)seed, intlen)

Description

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


Methodprf_tls_1_2

string(8bit)prf_tls_1_2(string(8bit)secret, string(8bit)label, string(8bit)seed, intlen)

Description

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

Class SSL.Cipher.CipherAlgorithm

Description

Cipher algorithm interface.


Methodblock_size

int(0..)block_size()

Description

Return the block size for this crypto.


Methodset_encrypt_key
Methodset_decrypt_key

this_programset_encrypt_key(string)
this_programset_decrypt_key(string)

Description

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

Class SSL.Cipher.CipherSpec

Description

Cipher specification.


Variablebulk_cipher_algorithm

program SSL.Cipher.CipherSpec.bulk_cipher_algorithm

Description

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


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


Variablehash

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.


Variablehash_size

int SSL.Cipher.CipherSpec.hash_size

Description

The number of bytes in the MAC hashes.


Variableis_exportable

int SSL.Cipher.CipherSpec.is_exportable

Description

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


Variableiv_size

int SSL.Cipher.CipherSpec.iv_size

Description

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


Variableke_factory

program SSL.Cipher.CipherSpec.ke_factory

Description

Key exchange factory.


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


Variablekey_material

int SSL.Cipher.CipherSpec.key_material

Description

The number of bytes of key material used on initialization.


Variablemac_algorithm

program SSL.Cipher.CipherSpec.mac_algorithm

Description

The Message Authentication Code to use for the packets.


Variableprf

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


Methodsign

ADT.structsign(objectsession, string(8bit)cookie, ADT.structstruct)

Description

The function used to sign packets.


Variablesignature_alg

SignatureAlgorithm SSL.Cipher.CipherSpec.signature_alg

Description

The signature algorithm used for key exchange signatures.


Variablesignature_hash

HashAlgorithm SSL.Cipher.CipherSpec.signature_hash

Description

The hash algorithm used for key exchange signatures.


Methodverify

boolverify(objectsession, stringcookie, ADT.structstruct, ADT.structinput)

Description

The function used to verify the signature for packets.

Class SSL.Cipher.DES


InheritState

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

Class SSL.Cipher.DES3


InheritState

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.


Methodcreate

SSL.Cipher.DHKeyExchangeSSL.Cipher.DHKeyExchange(Crypto.DH.Parametersp)


Variableparameters

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

Description

Finite field Diffie-Hellman parameters.


Methodset_other

this_programset_other(Gmp.mpzo)

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.


Variableanonymous

int SSL.Cipher.KeyExchange.anonymous

Description

Indicates whether a certificate isn't required.


Methodclient_key_exchange_packet

stringclient_key_exchange_packet(stringclient_random, stringserver_random, ProtocolVersionversion)

Returns

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


Variablecontext
Variablesession
Variableconnection
Variableclient_version

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


Methodcreate

SSL.Cipher.KeyExchangeSSL.Cipher.KeyExchange(objectcontext, objectsession, objectconnection, ProtocolVersionclient_version)


Methodderive_master_secret

stringderive_master_secret(stringpremaster_secret, stringclient_random, stringserver_random, ProtocolVersionversion)

Description

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

Returns

Returns the master secret.


Variablemessage_was_bad

int SSL.Cipher.KeyExchange.message_was_bad

Description

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


Methodparse_server_key_exchange

ADT.structparse_server_key_exchange(ADT.structinput)

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.


Methodserver_derive_master_secret

string(8bit)|int(8bit)server_derive_master_secret(string(8bit)data, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

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.


Methodserver_key_exchange

intserver_key_exchange(ADT.structinput, stringclient_random, stringserver_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.


Methodserver_key_exchange_packet

stringserver_key_exchange_packet(stringclient_random, stringserver_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.


Methodserver_key_params

ADT.structserver_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.


InheritKeyExchange

inherit KeyExchange : KeyExchange


Methodserver_derive_master_secret

string(8bit)|int(8bit)server_derive_master_secret(string(8bit)data, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

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.


InheritKeyExchangeDH

inherit KeyExchangeDH : KeyExchangeDH


Methodserver_derive_master_secret

string(8bit)|int(8bit)server_derive_master_secret(string(8bit)data, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

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.


InheritKeyExchange

inherit KeyExchange : KeyExchange


Methodserver_derive_master_secret

string(8bit)|int(8bit)server_derive_master_secret(string(8bit)data, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

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.


InheritKeyExchangeECDH

inherit KeyExchangeECDH : KeyExchangeECDH


Methodserver_derive_master_secret

string(8bit)|int(8bit)server_derive_master_secret(string(8bit)data, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

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.


InheritKeyExchange

inherit KeyExchange : KeyExchange


Methodserver_derive_master_secret

string(8bit)server_derive_master_secret(string(8bit)data, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

Returns

Master secret or alert number.

Class SSL.Cipher.KeyExchangeRSA

Description

Key exchange for KE_rsa.

KeyExchange that uses the Rivest Shamir Adelman algorithm.


InheritKeyExchange

inherit KeyExchange : KeyExchange


Methodserver_derive_master_secret

string(8bit)|int(8bit)server_derive_master_secret(string(8bit)data, string(8bit)client_random, string(8bit)server_random, ProtocolVersionversion)

Returns

Master secret or alert number.

Class SSL.Cipher.MACAlgorithm

Description

Message Authentication Code interface.


Methodblock_size

intblock_size()

Description

The block size of the underlying hash algorithm.


Methodhash

stringhash(stringdata)

Description

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


Constanthash_header_size

constantint SSL.Cipher.MACAlgorithm.hash_header_size

Description

The length of the header prefixed by hash().


Methodhash_packet

stringhash_packet(objectpacket, intseq_num, int|voidadjust_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.


Methodhash_raw

stringhash_raw(stringdata)

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.


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


Methodcreate

SSL.Cipher.MAChmac_shaSSL.Cipher.MAChmac_sha(string|voids)


InheritMACAlgorithm

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.


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


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


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


InheritMACsha

inherit MACsha : MACsha

Class SSL.Cipher.MACsha

Description

MAC using SHA.

Note

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


InheritMACAlgorithm

inherit MACAlgorithm : MACAlgorithm

Class SSL.Cipher.RC2


InheritState

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

Module SSL.Constants

Description

Protocol constants


ConstantCIPHER_effective_keylengths

constant SSL.Constants.CIPHER_effective_keylengths

Description

Mapping from cipher algorithm to effective key length.


ConstantECC_NAME_TO_CURVE

constant SSL.Constants.ECC_NAME_TO_CURVE

Description

Lookup for Pike ECC name to NamedCurve.


ConstantHASH_lookup

constant SSL.Constants.HASH_lookup

Description

Lookup from HashAlgorithm to corresponding Crypto.Hash.


ConstantKE_Anonymous

constant SSL.Constants.KE_Anonymous

Description

Lists KeyExchangeType that doesn't require certificates.


ConstantPROTOCOL_SSL_MAX
ConstantPROTOCOL_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.


ConstantCERTTYPE_x509
ConstantCERTTYPE_openpgp
ConstantCERTTYPE_raw_public_key

constant SSL.Constants.CERTTYPE_x509
constant SSL.Constants.CERTTYPE_openpgp
constant SSL.Constants.CERTTYPE_raw_public_key

Enum SSL.Constants.CipherModes

Description

Cipher operation modes.


ConstantMODE_cbc

constant SSL.Constants.MODE_cbc

Description

CBC - Cipher Block Chaining mode.


ConstantMODE_ccm

constant SSL.Constants.MODE_ccm

Description

CCM - Counter with CBC-MAC mode.


ConstantMODE_ccm_8

constant SSL.Constants.MODE_ccm_8

Description

CCM - Counter with 8 bit CBC-MAC mode.


ConstantMODE_gcm

constant SSL.Constants.MODE_gcm

Description

GCM - Galois Cipher Mode.


ConstantMODE_poly1305

constant SSL.Constants.MODE_poly1305

Description

Poly1305 - Used only with ChaCha20.

Enum SSL.Constants.CompressionType

Description

Compression methods.


ConstantCOMPRESSION_deflate

constant SSL.Constants.COMPRESSION_deflate

Description

Deflate compression. RFC 3749


ConstantCOMPRESSION_lzs

constant SSL.Constants.COMPRESSION_lzs

Description

LZS compression. RFC 3943


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


ConstantCONNECTION_closed

constant SSL.Constants.CONNECTION_closed

Description

Closed at both ends.


ConstantCONNECTION_closing

constant SSL.Constants.CONNECTION_closing

Description

Connection closing mask.


ConstantCONNECTION_failing

constant SSL.Constants.CONNECTION_failing

Description

Connection failing mask.


ConstantCONNECTION_handshaking

constant SSL.Constants.CONNECTION_handshaking

Description

Handshaking not done.


ConstantCONNECTION_local_closed

constant SSL.Constants.CONNECTION_local_closed

Description

Local close packet sent.


ConstantCONNECTION_local_closing

constant SSL.Constants.CONNECTION_local_closing

Description

Local close packet pending.


ConstantCONNECTION_local_down

constant SSL.Constants.CONNECTION_local_down

Description

Local mask.


ConstantCONNECTION_local_failing

constant SSL.Constants.CONNECTION_local_failing

Description

Fatal alert pending.


ConstantCONNECTION_local_fatal

constant SSL.Constants.CONNECTION_local_fatal

Description

Fatal alert sent.


ConstantCONNECTION_peer_closed

constant SSL.Constants.CONNECTION_peer_closed

Description

Peer has closed the connection.


ConstantCONNECTION_peer_down

constant SSL.Constants.CONNECTION_peer_down

Description

Peer mask.


ConstantCONNECTION_peer_fatal

constant SSL.Constants.CONNECTION_peer_fatal

Description

Peer has issued a fatal alert.


ConstantCONNECTION_ready

constant SSL.Constants.CONNECTION_ready

Description

Connection is ready for use.

Enum SSL.Constants.FragmentLength

Description

Fragment lengths for EXTENSION_max_fragment_length.


ConstantFRAGMENT_512
ConstantFRAGMENT_1024
ConstantFRAGMENT_2048
ConstantFRAGMENT_4096

constant SSL.Constants.FRAGMENT_512
constant SSL.Constants.FRAGMENT_1024
constant SSL.Constants.FRAGMENT_2048
constant SSL.Constants.FRAGMENT_4096

Enum SSL.Constants.HashAlgorithm

Description

Hash algorithms as per RFC 5246 7.4.1.4.1.


ConstantHASH_none
ConstantHASH_md5
ConstantHASH_sha
ConstantHASH_sha224
ConstantHASH_sha256
ConstantHASH_sha384
ConstantHASH_sha512

constant SSL.Constants.HASH_none
constant SSL.Constants.HASH_md5
constant SSL.Constants.HASH_sha
constant SSL.Constants.HASH_sha224
constant SSL.Constants.HASH_sha256
constant SSL.Constants.HASH_sha384
constant SSL.Constants.HASH_sha512

Enum SSL.Constants.KeyExchangeType

Description

Key exchange methods.


ConstantKE_dh_anon

constant SSL.Constants.KE_dh_anon

Description

Diffie-Hellman Anonymous


ConstantKE_dh_dss

constant SSL.Constants.KE_dh_dss

Description

Diffie-Hellman cert signed with DSS


ConstantKE_dh_rsa

constant SSL.Constants.KE_dh_rsa

Description

Diffie-Hellman cert signed with RSA


ConstantKE_dhe_dss

constant SSL.Constants.KE_dhe_dss

Description

Diffie-Hellman Ephemeral DSS


ConstantKE_dhe_psk

constant SSL.Constants.KE_dhe_psk

Description

Preshared Key with DHE


ConstantKE_dhe_rsa

constant SSL.Constants.KE_dhe_rsa

Description

Diffie-Hellman Ephemeral RSA


ConstantKE_dms
ConstantKE_fortezza

constant SSL.Constants.KE_dms
constant SSL.Constants.KE_fortezza


ConstantKE_ecdh_anon

constant SSL.Constants.KE_ecdh_anon

Description

Elliptic Curve DH Anonymous


ConstantKE_ecdh_ecdsa

constant SSL.Constants.KE_ecdh_ecdsa

Description

Elliptic Curve DH cert signed with ECDSA


ConstantKE_ecdh_rsa

constant SSL.Constants.KE_ecdh_rsa

Description

Elliptic Curve DH cert signed with RSA


ConstantKE_ecdhe_ecdsa

constant SSL.Constants.KE_ecdhe_ecdsa

Description

Elliptic Curve DH Ephemeral with ECDSA


ConstantKE_ecdhe_rsa

constant SSL.Constants.KE_ecdhe_rsa

Description

Elliptic Curve DH Ephemeral with RSA


ConstantKE_null

constant SSL.Constants.KE_null

Description

None.


ConstantKE_psk

constant SSL.Constants.KE_psk

Description

Preshared Key


ConstantKE_rsa

constant SSL.Constants.KE_rsa

Description

Rivest-Shamir-Adelman


ConstantKE_rsa_fips

constant SSL.Constants.KE_rsa_fips

Description

Rivest-Shamir-Adelman with FIPS keys.


ConstantKE_rsa_psk

constant SSL.Constants.KE_rsa_psk

Description

Preshared Key signed with RSA


ConstantKE_srp_sha

constant SSL.Constants.KE_srp_sha

Description

Secure Remote Password (SRP)


ConstantKE_srp_sha_dss

constant SSL.Constants.KE_srp_sha_dss

Description

SRP signed with DSS


ConstantKE_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


ConstantPROTOCOL_SSL_3_0

constant SSL.Constants.PROTOCOL_SSL_3_0

Description

SSL 3.0 - The original SSL3 draft version.


ConstantPROTOCOL_SSL_3_1

constant SSL.Constants.PROTOCOL_SSL_3_1

Description

SSL 3.1 - The RFC 2246 version of SSL.


ConstantPROTOCOL_SSL_3_2

constant SSL.Constants.PROTOCOL_SSL_3_2

Description

SSL 3.2 - The RFC 4346 version of SSL.


ConstantPROTOCOL_SSL_3_3

constant SSL.Constants.PROTOCOL_SSL_3_3

Description

SSL 3.3 - The RFC 5246 version of SSL.


ConstantPROTOCOL_TLS_1_0

constant SSL.Constants.PROTOCOL_TLS_1_0

Description

TLS 1.0 - The RFC 2246 version of TLS.


ConstantPROTOCOL_TLS_1_1

constant SSL.Constants.PROTOCOL_TLS_1_1

Description

TLS 1.1 - The RFC 4346 version of TLS.


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


ConstantSIGNATURE_anonymous

constant SSL.Constants.SIGNATURE_anonymous

Description

No signature.


ConstantSIGNATURE_dsa

constant SSL.Constants.SIGNATURE_dsa

Description

DSS signature.


ConstantSIGNATURE_ecdsa

constant SSL.Constants.SIGNATURE_ecdsa

Description

ECDSA signature.


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


Variablecert_type

int SSL.Constants.CertificatePair.cert_type

Description

Cerificate type for the leaf cert.

One of the AUTH_* constants.


Variablecerts

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

Description

Chain of certificates, root cert last.


Methodcreate

SSL.Constants.CertificatePairSSL.Constants.CertificatePair(Crypto.Sign.Statekey, array(string(8bit)) certs, array(string(8bit))|voidextra_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.


Variableglobs

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

Description

Array of commonName globs from the first certificate in certs.


Variableissuers

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

Description

Array of DER for the issuers matching certs.


Variableke_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


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


Variablekey

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

Description

Private key.


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


MethodXXX
Methodasync_XXX
Methodasync_cb_XXX

mixedXXX(mixed ... args)
objectasync_XXX(mixed ... args)
objectasync_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.


Methodcreate

Protocols.LysKOM.ConnectionProtocols.LysKOM.Connection(stringserver)
Protocols.LysKOM.ConnectionProtocols.LysKOM.Connection(stringserver, mappingoptions)

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


Variableprotocol_level
Variablesession_software
Variablesoftware_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


Methodconference

Conferenceconference(intno)

Description

Returns conference number no.


Methodcreate

Protocols.LysKOM.SessionProtocols.LysKOM.Session(stringserver)
Protocols.LysKOM.SessionProtocols.LysKOM.Session(stringserver, mappingoptions)

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


Methodcreate_person

objectcreate_person(stringname, stringpassword)

Description

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


Methodcreate_text

objectcreate_text(stringsubject, stringbody, mappingoptions)
objectcreate_text(stringsubject, stringbody, mappingoptions, 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()


Methodlogin

objectlogin(intuser_no, stringpassword)
objectlogin(intuser_no, stringpassword, intinvisible)

Description

Performs a login. Throws a lyskom error if unsuccessful.

Returns

The session object logged in.


Methodlogout

this_programlogout()

Description

Logouts from the server. returns the called object


Methodperson

Personperson(intno)

Description

Returns the Personno.


Methodregister_async_message_callback

voidregister_async_message_callback(function(int, int, string:void) cb)


Methodsend_message

object|voidsend_message(stringtextstring, mappingoptions)

Description

Sends a message.

options is a mapping that may contain:

"recpt" : Conference

recipient conference.


Methodtext

Texttext(intno)

Description

Returns the text no.


Methodtry_complete_person

array(ProtocolTypes.ConfZInfo) try_complete_person(stringorig)

Description

Runs a LysKOM completion on the given string, returning an array of confzinfos of the match.


Variableuser

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


InheritAuxItemInput

inherit ProtocolTypes.AuxItemInput : AuxItemInput

Class Protocols.LysKOM.Session.AuxItems

FIXME

Undocumented

Class Protocols.LysKOM.Session.Conference


Variableprefetch_stat
Variableno
Variableerror
Variablemsg_of_day
Variablesupervisor
Variablepermitted_submitters
Variablesuper_conf
Variablecreator
Variableaux_items
Variablename
Variabletype
Variablecreation_time
Variablelast_written
Variablenice
Variableno_of_members
Variablefirst_local_no
Variableno_of_texts
Variablepresentation

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


Methodcreate

Protocols.LysKOM.Session.ConferenceProtocols.LysKOM.Session.Conference(intno)

Class Protocols.LysKOM.Session.Membership

Description

All variables in this class is read only.


Variableadded_at

object Protocols.LysKOM.Session.Membership.added_at


Variableconf

object Protocols.LysKOM.Session.Membership.conf


Variablelast_text_read

int Protocols.LysKOM.Session.Membership.last_text_read


Variablelast_time_read

object Protocols.LysKOM.Session.Membership.last_time_read


Methodnumber_unread

intnumber_unread()


Variableposition

int Protocols.LysKOM.Session.Membership.position


Variablepriority

int(8bit) Protocols.LysKOM.Session.Membership.priority


Methodquery_read_texts

voidquery_read_texts()


Variableread_texts

array(int) Protocols.LysKOM.Session.Membership.read_texts


Variabletype

multiset(string) Protocols.LysKOM.Session.Membership.type


Methodunread_texts

array(object) unread_texts()

Class Protocols.LysKOM.Session.Person


Variableerror
Variableuser_area
Variableusername
Variableprivileges
Variableflags
Variablelast_login
Variabletotal_time_present
Variablesessions
Variablecreated_lines
Variablecreated_bytes
Variableread_texts
Variableno_of_text_fetches
Variablecreated_persons
Variablecreated_confs
Variablefirst_created_local_no
Variableno_of_created_texts
Variableno_of_marks
Variableno_of_confs
Variableunread
Variableclear_membership
Variablemembership

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


Methodcreate

Protocols.LysKOM.Session.PersonProtocols.LysKOM.Session.Person(intno)


Variableno

int Protocols.LysKOM.Session.Person.no


Variableprefetch_stat
Variableprefetch_conf
Variableprefetch_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


Variableauthor

string Protocols.LysKOM.Session.Text.author

Description

The author of the text.


Variableprefetch_text
Variableprefetch_stat
Variablelines
Variablecharacters
Variableclear_stat
Variableaux_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


Methodcreate

Protocols.LysKOM.Session.TextProtocols.LysKOM.Session.Text(stringtextnumber)

Description

Initializes a Text object.


Variablecreation_time

mixed Protocols.LysKOM.Session.Text.creation_time

Description

The time the text was created on the server.


Variableerr

object Protocols.LysKOM.Session.Text.err

Description

Undocumented


Methodmark_as_read

voidmark_as_read()

FIXME

Undocumented.


Variablemarks

int Protocols.LysKOM.Session.Text.marks

Description

The number of marks on this text.


Variablemisc

mixed Protocols.LysKOM.Session.Text.misc

Description

Misc info, including what conferences the message is posted to.

FIXME

Needs a more complete description.


Variableno

int Protocols.LysKOM.Session.Text.no

Description

The text number, as spicified to create.


Variablesubject

string Protocols.LysKOM.Session.Text.subject

Description

The message subject.


Variabletext

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(intcall, mixed_data)
mixed_sync(intcall, 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
Methodreply

mixed_reply(object|arraywhat)
mixedreply(object|arraywhat)

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.


Methodasync
Methodsync

voidasync(mixed ... args)
mixedsync(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.


Variableerror

object Protocols.LysKOM.Request._Request.error

Description

How the call failed. The call has completed if (ok||error).


Variableok

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


ConstantFORMERR

final constantint Protocols.DNS.FORMERR

Description

The name server was unable to interpret the request due to a format error.


ConstantNOERROR

final constantint Protocols.DNS.NOERROR

Description

No error condition.


ConstantNOTIMPL

final constantint Protocols.DNS.NOTIMPL

Description

The name server does not support the specified Opcode.


ConstantNXDOMAIN

final constantint Protocols.DNS.NXDOMAIN

Description

Some name that ought to exist, does not exist.


ConstantNXRRSET

final constantint Protocols.DNS.NXRRSET

Description

Some RRset that ought to exist, does not exist.


ConstantREFUSED

final constantint Protocols.DNS.REFUSED

Description

The name server refuses to perform the specified operation for policy or security reasons.


ConstantSERVFAIL

final constantint 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.


Methodasync_get_mx

voidasync_get_mx(stringhost, function(:void) cb, mixed ... cba)


Methodasync_get_mx_all

voidasync_get_mx_all(stringhost, function(:void) cb, mixed ... cba)


Methodasync_host_to_ip

voidasync_host_to_ip(stringhost, function(:void) cb, mixed ... cba)


Methodasync_ip_to_host

voidasync_ip_to_host(stringip, function(:void) cb, mixed ... cba)


Methodget_mx

stringget_mx(stringhost)


Methodget_primary_mx

stringget_primary_mx(stringhost)


Methodgethostbyaddr

arraygethostbyaddr(stringhost)


Methodgethostbyname

arraygethostbyname(stringhost)

Enum Protocols.DNS.EntryType

Description

Entry types


ConstantT_A

constant Protocols.DNS.T_A

Description

Type - host address


ConstantT_A6

constant Protocols.DNS.T_A6

Description

Type - IPv6 address record (RFC 2874 Obsolete RFC 6563)


ConstantT_AAAA

constant Protocols.DNS.T_AAAA

Description

Type - IPv6 address record (RFC 1886)


ConstantT_AFSDB

constant Protocols.DNS.T_AFSDB

Description

Type - AFC database record (RFC 1183)


ConstantT_ANY

constant Protocols.DNS.T_ANY

Description

Type - ANY - A request for all records


ConstantT_APL

constant Protocols.DNS.T_APL

Description

Type - Address Prefix List (RFC 3123)


ConstantT_ATMA

constant Protocols.DNS.T_ATMA

Description

Type - ATM End System Address (af-saa-0069.000)


ConstantT_AXFR

constant Protocols.DNS.T_AXFR

Description

Type - Authoritative Zone Transfer (RFC 1035)


ConstantT_CAA

constant Protocols.DNS.T_CAA

Description

Type - Certificate Authority Authorization (RFC 6844)


ConstantT_CERT

constant Protocols.DNS.T_CERT

Description

Type - Certificate Record (RFC 4398)


ConstantT_CNAME

constant Protocols.DNS.T_CNAME

Description

Type - canonical name for an alias


ConstantT_DHCID

constant Protocols.DNS.T_DHCID

Description

Type - DHCP identifier (RFC 4701)


ConstantT_DLV

constant Protocols.DNS.T_DLV

Description

Type - DNSSEC Lookaside Validation Record (RFC 4431)


ConstantT_DNAME

constant Protocols.DNS.T_DNAME

Description

Type - Delegation Name (RFC 2672)


ConstantT_DNSKEY

constant Protocols.DNS.T_DNSKEY

Description

Type - DNS Key record (RFC 4034)


ConstantT_DS

constant Protocols.DNS.T_DS

Description

Type - Delegation Signer (RFC 4034)


ConstantT_EID

constant Protocols.DNS.T_EID

Description

Type - Nimrod Endpoint IDentifier (draft)


ConstantT_UINFO
ConstantT_UID
ConstantT_GID
ConstantT_UNSPEC

constant Protocols.DNS.T_UINFO
constant Protocols.DNS.T_UID
constant Protocols.DNS.T_GID
constant Protocols.DNS.T_UNSPEC


ConstantT_GPOS

constant Protocols.DNS.T_GPOS

Description

Type - Global Position (RFC 1712 Obsolete use LOC).


ConstantT_HINFO

constant Protocols.DNS.T_HINFO

Description

Type - host information


ConstantT_HIP

constant Protocols.DNS.T_HIP

Description

Type - Host Identity Protocol (RFC 5205)


ConstantT_IPSECKEY

constant Protocols.DNS.T_IPSECKEY

Description

Type - IPsec Key (RFC 4025)


ConstantT_ISDN

constant Protocols.DNS.T_ISDN

Description

Type - ISDN address (RFC 1183)


ConstantT_IXFR

constant Protocols.DNS.T_IXFR

Description

Type - Incremental Zone Transfer (RFC 1996)


ConstantT_KEY

constant Protocols.DNS.T_KEY

Description

Type - Key record (RFC 2535 and RFC 2930)


ConstantT_KX

constant Protocols.DNS.T_KX

Description

Type - Key eXchanger record (RFC 2230)


ConstantT_LOC

constant Protocols.DNS.T_LOC

Description

Type - Location Record (RFC 1876)


ConstantT_MAILA

constant Protocols.DNS.T_MAILA

Description

Type - Mail Agent (both MD and MF) (Obsolete - use MX)


ConstantT_MAILB

constant Protocols.DNS.T_MAILB

Description

Type - Mail Box (MB, MG or MR) (Obsolete - use MX)


ConstantT_MB

constant Protocols.DNS.T_MB

Description

Type - mailbox domain name (Obsolete)


ConstantT_MD

constant Protocols.DNS.T_MD

Description

Type - mail destination (Obsolete - use MX)


ConstantT_MF

constant Protocols.DNS.T_MF

Description

Type - mail forwarder (Obsolete - use MX)


ConstantT_MG

constant Protocols.DNS.T_MG

Description

Type - mail group member (Obsolete)


ConstantT_MINFO

constant Protocols.DNS.T_MINFO

Description

Type - mailbox or mail list information (Obsolete)


ConstantT_MR

constant Protocols.DNS.T_MR

Description

Type - mail rename domain name (Obsolete)


ConstantT_MX

constant Protocols.DNS.T_MX

Description

Type - mail exchange


ConstantT_NAPTR

constant Protocols.DNS.T_NAPTR

Description

Type - NAPTR (RFC 3403)


ConstantT_NIMLOC

constant Protocols.DNS.T_NIMLOC

Description

Type - Nimrod Locator (draft)


ConstantT_NS

constant Protocols.DNS.T_NS

Description

Type - authoritative name server


ConstantT_NSAP

constant Protocols.DNS.T_NSAP

Description

Type - OSI Network Service Access Protocol (RFC 1348, RFC 1637, RFC 1706)


ConstantT_NSAP_PTR

constant Protocols.DNS.T_NSAP_PTR

Description

Type - OSI NSAP Pointer (RFC 1348, Obsolete RFC 1637)


ConstantT_NSEC

constant Protocols.DNS.T_NSEC

Description

Type - Next-Secure record (RFC 4034)


ConstantT_NSEC3

constant Protocols.DNS.T_NSEC3

Description

Type - NSEC record version 3 (RFC 5155)


ConstantT_NSEC3PARAM

constant Protocols.DNS.T_NSEC3PARAM

Description

Type - NSEC3 parameters (RFC 5155)


ConstantT_NULL

constant Protocols.DNS.T_NULL

Description

Type - null RR (Obsolete RFC 1035)


ConstantT_NXT

constant Protocols.DNS.T_NXT

Description

Type - Next (RFC 2065, Obsolete RFC 3755)


ConstantT_OPT

constant Protocols.DNS.T_OPT

Description

Type - Option (RFC 2671)


ConstantT_PTR

constant Protocols.DNS.T_PTR

Description

Type - domain name pointer


ConstantT_PX

constant Protocols.DNS.T_PX

Description

Type - Pointer to X.400 mapping information (RFC 1664)


ConstantT_RP

constant Protocols.DNS.T_RP

Description

Type - Responsible Person


ConstantT_RRSIG

constant Protocols.DNS.T_RRSIG

Description

Type - DNSSEC signature (RFC 4034)


ConstantT_RT

constant Protocols.DNS.T_RT

Description

Type - Route Through (RFC 1183)


ConstantT_SIG

constant Protocols.DNS.T_SIG

Description

Type - Signature (RFC 2535)


ConstantT_SINK

constant Protocols.DNS.T_SINK

Description

Type - Kitchen Sink (draft)


ConstantT_SOA

constant Protocols.DNS.T_SOA

Description

Type - start of a zone of authority


ConstantT_SPF

constant Protocols.DNS.T_SPF

Description

Type - SPF - Sender Policy Framework (RFC 4408)


ConstantT_SRV

constant Protocols.DNS.T_SRV

Description

Type - Service location record (RFC 2782)


ConstantT_SSHFP

constant Protocols.DNS.T_SSHFP

Description

Type - SSH Public Key Fingerprint (RFC 4255)


ConstantT_TA

constant Protocols.DNS.T_TA

Description

Type - DNSSEC Trust Authorities (draft)


ConstantT_TKEY

constant Protocols.DNS.T_TKEY

Description

Type - Secret key record (RFC 2930)


ConstantT_TLSA

constant Protocols.DNS.T_TLSA

Description

Type - TLSA certificate association (RFC 6698)


ConstantT_TSIG

constant Protocols.DNS.T_TSIG

Description

Type - Transaction Signature (RFC 2845)


ConstantT_TXT

constant Protocols.DNS.T_TXT

Description

Type - text strings


ConstantT_WKS

constant Protocols.DNS.T_WKS

Description

Type - well known service description (Obsolete RFC 1123, RFC 1127)


ConstantT_X25

constant Protocols.DNS.T_X25

Description

Type - X25 PSDN address (RFC 1183)

Enum Protocols.DNS.ResourceClass

Description

Resource classes


ConstantC_ANY

constant Protocols.DNS.C_ANY

Description

Class ANY


ConstantC_CH

constant Protocols.DNS.C_CH

Description

Class CHAOS


ConstantC_CS

constant Protocols.DNS.C_CS

Description

Class CSNET (Obsolete)


ConstantC_HS

constant Protocols.DNS.C_HS

Description

Class Hesiod


ConstantC_IN

constant Protocols.DNS.C_IN

Description

Class Internet

Class Protocols.DNS.async_client

Description

Asynchronous DNS client.


Methodclose

voidclose()

Description

Close the client.

Note

All active requests are aborted.


Methodcreate

Protocols.DNS.async_clientProtocols.DNS.async_client(void|string|array(string) server, void|string|array(string) domain)


Methoddo_query

Requestdo_query(stringdomain, intcl, inttype, 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.


Methodget_mx

Requestget_mx(stringhost, function(:void) callback, mixed ... args)


Methodget_mx_all

Requestget_mx_all(stringhost, function(:void) callback, mixed ... args)


Methodhost_to_ip

Requesthost_to_ip(stringhost, function(:void) callback, mixed ... args)


Inheritclient

inherit client : client


Inheritudp

inherit Stdio.UDP : udp


Methodip_to_host

Requestip_to_host(stringip, function(:void) callback, mixed ... args)

Class Protocols.DNS.async_dual_client

Description

Both an async_client and an async_tcp_client.


Methoddo_query

Requestdo_query(stringdomain, intcl, inttype, function(string, mapping, mixed ... :void) callback, mixed ... args)


InheritTCP

inherit async_tcp_client : TCP


InheritUDP

inherit async_client : UDP

Class Protocols.DNS.async_tcp_client

Description

Asynchronous DNS client using TCP


Methoddo_query

Requestdo_query(stringdomain, intcl, inttype, function(string, mapping, mixed ... :void) callback, mixed ... args)


Inheritasync_client

inherit async_client : async_client

Class Protocols.DNS.async_tcp_client.Request


Inheritthis_program

inherit ::this_program : this_program

Class Protocols.DNS.client

Description

Synchronous DNS client.


Methodcreate

Protocols.DNS.clientProtocols.DNS.client()
Protocols.DNS.clientProtocols.DNS.client(void|string|arrayserver, void|int|arraydomain)


Methoddo_sync_query

mappingdo_sync_query(strings)

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
<span class='comment'>// Perform a hostname lookup, results stored in r->an</span>
    <span class='type'>object</span> d<span class='delim'>=</span><span class='ns'>Protocols</span><span class='delim'>.</span>DNS<span class='delim'>.</span>client<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span>
    <span class='type'>mapping</span> r<span class='delim'>=</span>d->do_sync_query<span class='delim'>(</span>d->mkquery<span class='delim'>(</span><span class='string'>"pike.lysator.liu.se"</span><span class='delim'>,</span> C_IN<span class='delim'>,</span> T_A<span class='delim'>)</span><span class='delim'>)</span><span class='delim'>;</span>

Methodget_mx

array(string) get_mx(stringhost)


Methodget_primary_mx

stringget_primary_mx(stringhostname)

Description

Queries the primary mx for the host.

Returns

Returns the hostname of the primary mail exchanger.


Methodgethostbyaddr

arraygethostbyaddr(stringhostip)

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
stringhostip

The host IP.

array(string) ip

IP number(s).

array(string) aliases

DNS name(s).


Methodgethostbyname

arraygethostbyname(stringhostname)

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
stringhostname

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.


Methodgetsrvbyname

arraygetsrvbyname(stringservice, stringprotocol, string|voidname)

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
intpriority

Priority

intweight

Weight in event of multiple records with same priority.

intport

port number

stringtarget

target dns name


Inheritprotocol

inherit protocol : protocol

Class Protocols.DNS.client.Request


Variabledomain
Variablereq
Variablecallback
Variableargs

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

voidcancel()mixed Protocols.DNS.client.Request.retry_co

Description

Cancel the current request.


Methodcreate

Protocols.DNS.client.RequestProtocols.DNS.client.Request(stringdomain, stringreq, function(string, mapping, mixed ... :void) callback, array(mixed) args)

Class Protocols.DNS.dual_client

Description

Both a client and a tcp_client.


Methoddo_sync_query

mappingdo_sync_query(strings)


InheritTCP

inherit tcp_client : TCP


InheritUDP

inherit client : UDP

Class Protocols.DNS.dual_server

Description

This is both a server and tcp_server.


InheritTCP

inherit tcp_server : TCP


InheritUDP

inherit server : UDP

Class Protocols.DNS.protocol

Description

Low level DNS protocol


Methoddecode_entries

arraydecode_entries(strings, intnum, 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
mapping0..

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

Methodmkquery

stringmkquery(string|mappingdnameorquery, int|voidcl, int|voidtype)

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


Methodcreate

Protocols.DNS.serverProtocols.DNS.server()
Protocols.DNS.serverProtocols.DNS.server(intport)
Protocols.DNS.serverProtocols.DNS.server(stringip)
Protocols.DNS.serverProtocols.DNS.server(stringip, intport)
Protocols.DNS.serverProtocols.DNS.server(stringip, intport, 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.


Inheritserver_base

inherit server_base : server_base

Class Protocols.DNS.server_base

Description

Base class for server, tcp_server.


Methodhandle_query

protectedvoidhandle_query(mappingq, mappingm, Stdio.UDP|objectudp)

Description

Handle a query.

This function calls reply_query(), and dispatches the result to send_reply().


Methodhandle_response

protectedvoidhandle_response(mappingr, mappingm, Stdio.UDP|objectudp)

Description

Handle a query response (stub).

Overload this function to handle responses to possible recursive queries.


Inheritprotocol

inherit protocol : protocol


Methodrec_data

protectedvoidrec_data(mappingm, Stdio.UDP|objectudp)

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


Methodreply_query

protectedmappingreply_query(mappingquery, mappingudp_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

Class Protocols.DNS.tcp_client

Description

Synchronous DNS client using TCP Can handle larger responses than client can.


Methoddo_sync_query

mappingdo_sync_query(strings)

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
<span class='comment'>// Perform a hostname lookup, results stored in r->an</span>
    <span class='type'>object</span> d<span class='delim'>=</span><span class='ns'>Protocols</span><span class='delim'>.</span>DNS<span class='delim'>.</span>tcp_client<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span>
    <span class='type'>mapping</span> r<span class='delim'>=</span>d->do_sync_query<span class='delim'>(</span>d->mkquery<span class='delim'>(</span><span class='string'>"pike.lysator.liu.se"</span><span class='delim'>,</span> C_IN<span class='delim'>,</span> T_A<span class='delim'>)</span><span class='delim'>)</span><span class='delim'>;</span>

Inheritclient

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


Methodcreate

Protocols.DNS.tcp_serverProtocols.DNS.tcp_server()
Protocols.DNS.tcp_serverProtocols.DNS.tcp_server(intport)
Protocols.DNS.tcp_serverProtocols.DNS.tcp_server(stringip)
Protocols.DNS.tcp_serverProtocols.DNS.tcp_server(stringip, intport)
Protocols.DNS.tcp_serverProtocols.DNS.tcp_server(stringip, intport, 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.


Inheritserver_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; }


Methodadd

this_programadd(stringpath, void|stringbase)

Description

Add a file, or a directory tree to the torrent. This will call add_directory_tree or add_file.


Methodadd_announce

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


Methodadd_directory_tree

this_programadd_directory_tree(stringpath, void|stringdirbase)

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.


Methodadd_file

this_programadd_file(stringpath, void|stringfilename)

Description

Add a file to the torrent. The second argument is what the file will be called in the torrent.


Methodbuild_sha1s

voidbuild_sha1s(void|function(int, int:void) progress_callback)

Description

Build the SHA hashes from the files.


Methodcreate

Protocols.Bittorrent.GeneratorProtocols.Bittorrent.Generator(void|stringbase, void|intpiece_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.


Methoddigest

stringdigest(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.


InheritTorrent

inherit .Torrent : Torrent

Class Protocols.Bittorrent.Peer


Methodconnect

voidconnect()

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


Methoddisconnect

voiddisconnect()

Description

Disconnect a peer. Does nothing if we aren't online. status/mode will change to "disconnected",1 if we were online.


Methoddownloading_pieces

multiset(int) downloading_pieces()

Description

Returns as multiset what this peer is downloading.


Methodis_activated

intis_activated()

Description

Returns true if this peer is activated, as in we're downloading from it.


Methodis_available

intis_available()

Description

Returns true if this peer is available, as in we can use it to download stuff.


Methodis_choked

intis_choked()

Description

Returns true if this peer is choking, as in doesn't send more data to us.


Methodis_completed

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


Methodis_connectable

intis_connectable()

Description

Returns true if we can connect to this peer, when new or disconnected but not fatally.


Methodis_online

intis_online()

Description

Returns true if this peer is online and connected.


Methodis_strangled

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


Methodrequest

voidrequest(intpiece, intoffset, intbytes, function(int, int, string, object:void|mixed) callback)

Description

Called to request a chunk from this peer.


Methodsend_have

voidsend_have(intn)

Description

Send a have message to tell I now have piece n. Ignored if not online.


Methodstatus

voidstatus(stringtype, void|int|stringdata)

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


Methodcreate

Protocols.Bittorrent.PortProtocols.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.

<span class='type'>int</span> main<span class='delim'>(</span><span class='type'>int</span> ac<span class='delim'>,</span><span class='type'>array</span> am<span class='delim'>)</span>
  <span class='delim'>{</span>
     <span class='comment'>// initialize Torrent from file:</span>
     <span class='ns'>Protocols</span><span class='delim'>.</span>Bittorrent<span class='delim'>.</span>Torrent t<span class='delim'>=</span><span class='ns'>Protocols</span><span class='delim'>.</span>Bittorrent<span class='delim'>.</span>Torrent<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span> 
     t->load_metainfo<span class='delim'>(</span>am<span class='delim'>[</span>1<span class='delim'>]</span><span class='delim'>)</span><span class='delim'>;</span> 

     <span class='comment'>// Callback when download status changes:</span>
     <span class='comment'>// t->downloads_update_status=...;</span>

     <span class='comment'>// Callback when pieces status change (when we get new stuff):</span>
     <span class='comment'>// t->pieces_update_status=...; </span>

     <span class='comment'>// Callback when peer status changes (connect, disconnect, choked...):</span>
     <span class='comment'>// t->peer_update_status=...;</span>

     <span class='comment'>// Callback when download is completed:</span>
     t->download_completed_callback<span class='delim'>=</span>
        <span class='lang'>lambda</span><span class='delim'>(</span><span class='delim'>)</span>
        <span class='delim'>{</span>
            call_out<span class='delim'>(</span>exit<span class='delim'>,</span>3600<span class='delim'>,</span>0<span class='delim'>)</span><span class='delim'>;</span>    <span class='comment'>// share for an hour, then exit</span>
        <span class='delim'>}</span><span class='delim'>;</span>

     <span class='comment'>// Callback to print warnings (same args as sprintf):</span>
     <span class='comment'>//   t->warning=werror; </span>

     <span class='comment'>// type of progress function used below:</span>
     <span class='type'>void</span> progress<span class='delim'>(</span><span class='type'>int</span> n<span class='delim'>,</span><span class='type'>int</span> of<span class='delim'>)</span> <span class='delim'>{</span> <span class='comment'>/* ... */</span> <span class='delim'>}</span><span class='delim'>;</span>

     <span class='comment'>// Initiate targets from Torrent,</span>
     <span class='comment'>// if target was created, no need to verify:</span>
     <span class='lang'>if</span> <span class='delim'>(</span>t->fix_targets<span class='delim'>(</span>1<span class='delim'>,</span>0<span class='delim'>,</span>progress<span class='delim'>)</span>==1<span class='delim'>)</span>
        t->verify_targets<span class='delim'>(</span>progress<span class='delim'>)</span><span class='delim'>;</span> 

     <span class='comment'>// Open port to listen on,</span>
     <span class='comment'>// we want to do this to be able to talk to firewalled peers:</span>
     t->open_port<span class='delim'>(</span>6881<span class='delim'>)</span><span class='delim'>;</span>

     <span class='comment'>// Ok, start calling tracker to get peers,</span>
     <span class='comment'>// and tell about us:</span>
     t->start_update_tracker<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span>

     <span class='comment'>// Finally, start the download:</span>
     t->start_download<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span>

     <span class='lang'>return</span> <span class='delim'>-</span>1<span class='delim'>;</span>
  <span class='delim'>}</span>

Methodbytes_done

intbytes_done()

Description

Calculate the bytes successfully downloaded (full pieces).


Methodbytes_left

intbytes_left()

Description

Calculate the bytes left to download.


Methodcontact_peers

voidcontact_peers(void|intn)

Description

Contact all or n peers.


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


Variabledownload_completed_callback

function(:void) Protocols.Bittorrent.Torrent.download_completed_callback

Description

If set, called when download is completed.


Variabledownloads_update_status

function(:void) Protocols.Bittorrent.Torrent.downloads_update_status

Description

If set, called when we start to download another piece (no args).


Methodfile_got_bitfield

stringfile_got_bitfield()

Description

Returns the file got field as a string bitfield (cached).


Methodfix_targets

intfix_targets(void|int(-1..2)allocate, void|stringbase_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.


Methodload_metainfo

voidload_metainfo(stringfilename)

Description

Loads the metainfo from a file.


Methodopen_port

voidopen_port(void|intport)

Description

Open the port we're listening on.


Variablepeer_update_status

function(:void) Protocols.Bittorrent.Torrent.peer_update_status

Description

If set, called when peer status changes.


Variablepieces_update_status

function(:void) Protocols.Bittorrent.Torrent.pieces_update_status

Description

If set, called when we got another piece downloaded (no args).


Methodstart_download

voidstart_download()

Description

Initiate the downloading scheme.


Methodstart_update_tracker

voidstart_update_tracker(void|intinterval)

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.


Methodstop_update_tracker

voidstop_update_tracker(void|stringevent)

Description

Stops updating the tracker; will send the event as a last event, if set. It will not contact new peers.


Methodupdate_tracker

voidupdate_tracker(void|stringevent, void|intcontact)

Description

Contact and update the tracker with current status will fill the peer list.


Methodverify_targets

voidverify_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) ]


Variablewarning

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.


Variablebase
Variablelength
Variableoffset
Variablepath

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


Methodcreate

Protocols.Bittorrent.Torrent.TargetProtocols.Bittorrent.Torrent.Target(stringbase, intlength, intoffset, void|arraypath)

Class Protocols.Bittorrent.Tracker


Methodadd_torrent

voidadd_torrent(stringid)

Description

Add a torrent to the tracker.

Parameter id

The info hash of the torrent file.


Methodannounce

stringannounce(mappingargs, stringip)

Description

Handles HTTP announce queries to the tracker.


Variabledynamic_add_torrents

bool Protocols.Bittorrent.Tracker.dynamic_add_torrents

Description

Allow clients to dynamically add torrents to the tracker.


Variableinterval

int(0..) Protocols.Bittorrent.Tracker.interval

Description

The query interval reported back to clients. Defaults to 1800.


Methodscrape

stringscrape(mappingargs)

Description

Returns the result of a scrape query.

Class Protocols.Bittorrent.Tracker.Client


Methodcreate

Protocols.Bittorrent.Tracker.ClientProtocols.Bittorrent.Tracker.Client(stringip, intport)


Variableip
Variableport

string Protocols.Bittorrent.Tracker.Client.ip
int Protocols.Bittorrent.Tracker.Client.port

Module Protocols.Bittorrent.Bencoding


Method_decode

array(string|int|array|mapping) _decode(stringwhat)

Description

Decodes a Bittorrent bencoded data chunk.

Returns
Array
string|int|array|mappingdata

The decoded data. UNDEFINED if no data could be decoded.

stringremainder

The trailing data that wasn't decoded.


Methodbits2string

stringbits2string(array(bool) v)

Description

Convert an array of int(0..1) to a Bittorrent style bitstring. Input will be padded to even bytes.


Methoddecode

string|int|array|mappingdecode(stringwhat)

Description

Decodes a Bittorrent bencoded data chunk and ignores the remaining string. Returns UNDEFINED if the data is incomplete.


Methodencode

stringencode(string|int|array|mappingdata)

Description

Encodes a Bittorrent bencoded data chunk.


Methodstring2arr

array(int) string2arr(strings)

Description

Convert a Bittorrent style bitstring to an array of indices.


Methodstring2bits

array(bool) string2bits(strings)

Description

Convert a Bittorrent style bitstring to an array of int(0..1).

Module Protocols.Bittorrent.PeerID


Methodidentify_peer

stringidentify_peer(stringpeerid)

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.


Methodcreate

Protocols.DNS_SD.ServiceProtocols.DNS_SD.Service(stringname, stringservice, stringdomain, intport, 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 );


InheritService

inherit _Protocols_DNS_SD.Service : Service


Methodupdate_txt

voidupdate_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


Methodformat_addr_short

stringformat_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


Methodnormalize_addr_basic

stringnormalize_addr_basic(stringaddr)

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


Methodnormalize_addr_short

stringnormalize_addr_short(stringaddr)

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


Methodparse_addr

array(int(16bit)) parse_addr(stringaddr)

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.


Variablename

string Protocols.IRC.Channel.name

Description

The name of the channel.

Class Protocols.IRC.Client


Methodclose

voidclose()

Description

Closes the connection to the server.


Methodcreate

Protocols.IRC.ClientProtocols.IRC.Client(string|objectserver, 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.


Variableip

string Protocols.IRC.Person.ip

Description

User domain, e.g. "mistel.idonex.se".


Variablelast_action

int Protocols.IRC.Person.last_action

Description

Time of last action, represented as posix time.


Variablenick

string Protocols.IRC.Person.nick

Description

User nickname, e.g. "Mirar".


Variableuser

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.


Methodlookup

array(string) lookup(objectfd)

Throws

Throws exception upon any error.

Class Protocols.Ident.AsyncLookup


Methodcreate

Protocols.Ident.AsyncLookupProtocols.Ident.AsyncLookup(objectfd, function(array(string), mixed ... :void) cb, mixed ... args)

Module Protocols.LDAP


ConstantGUID_USERS_CONTAINER
ConstantGUID_COMPUTERS_CONTAINER
ConstantGUID_SYSTEMS_CONTAINER
ConstantGUID_DOMAIN_CONTROLLERS_CONTAINER
ConstantGUID_INFRASTRUCTURE_CONTAINER
ConstantGUID_DELETED_OBJECTS_CONTAINER
ConstantGUID_LOSTANDFOUND_CONTAINER
ConstantGUID_FOREIGNSECURITYPRINCIPALS_CONTAINER
ConstantGUID_PROGRAM_DATA_CONTAINER
ConstantGUID_MICROSOFT_PROGRAM_DATA_CONTAINER
ConstantGUID_NTDS_QUOTAS_CONTAINER

constantstring Protocols.LDAP.GUID_USERS_CONTAINER
constantstring Protocols.LDAP.GUID_COMPUTERS_CONTAINER
constantstring Protocols.LDAP.GUID_SYSTEMS_CONTAINER
constantstring Protocols.LDAP.GUID_DOMAIN_CONTROLLERS_CONTAINER
constantstring Protocols.LDAP.GUID_INFRASTRUCTURE_CONTAINER
constantstring Protocols.LDAP.GUID_DELETED_OBJECTS_CONTAINER
constantstring Protocols.LDAP.GUID_LOSTANDFOUND_CONTAINER
constantstring Protocols.LDAP.GUID_FOREIGNSECURITYPRINCIPALS_CONTAINER
constantstring Protocols.LDAP.GUID_PROGRAM_DATA_CONTAINER
constantstring Protocols.LDAP.GUID_MICROSOFT_PROGRAM_DATA_CONTAINER
constantstring Protocols.LDAP.GUID_NTDS_QUOTAS_CONTAINER

Description

Constants for Microsoft AD Well-Known Object GUIDs. These are e.g. used in LDAP URLs:

<span class='string'>"ldap://server/<WKGUID="</span> <span class='delim'>+</span> <span class='ns'>Protocols</span><span class='delim'>.</span>LDAP<span class='delim'>.</span>GUID_USERS_CONTAINER <span class='delim'>+</span>
  <span class='string'>",dc=my,dc=domain,dc=com>"</span>

ConstantLDAP_SUCCESS
ConstantLDAP_OPERATIONS_ERROR
ConstantLDAP_PROTOCOL_ERROR
ConstantLDAP_TIMELIMIT_EXCEEDED
ConstantLDAP_SIZELIMIT_EXCEEDED
ConstantLDAP_COMPARE_FALSE
ConstantLDAP_COMPARE_TRUE
ConstantLDAP_AUTH_METHOD_NOT_SUPPORTED
ConstantLDAP_STRONG_AUTH_NOT_SUPPORTED
ConstantLDAP_STRONG_AUTH_REQUIRED
ConstantLDAP_PARTIAL_RESULTS
ConstantLDAP_REFERRAL
ConstantLDAP_ADMINLIMIT_EXCEEDED
ConstantLDAP_UNAVAILABLE_CRITICAL_EXTENSION
ConstantLDAP_CONFIDENTIALITY_REQUIRED
ConstantLDAP_SASL_BIND_IN_PROGRESS
ConstantLDAP_NO_SUCH_ATTRIBUTE
ConstantLDAP_UNDEFINED_TYPE
ConstantLDAP_INAPPROPRIATE_MATCHING
ConstantLDAP_CONSTRAINT_VIOLATION
ConstantLDAP_TYPE_OR_VALUE_EXISTS
ConstantLDAP_INVALID_SYNTAX
ConstantLDAP_NO_SUCH_OBJECT
ConstantLDAP_ALIAS_PROBLEM
ConstantLDAP_INVALID_DN_SYNTAX
ConstantLDAP_IS_LEAF
ConstantLDAP_ALIAS_DEREF_PROBLEM
ConstantLDAP_INAPPROPRIATE_AUTH
ConstantLDAP_INVALID_CREDENTIALS
ConstantLDAP_INSUFFICIENT_ACCESS
ConstantLDAP_BUSY
ConstantLDAP_UNAVAILABLE
ConstantLDAP_UNWILLING_TO_PERFORM
ConstantLDAP_LOOP_DETECT
ConstantLDAP_SORT_CONTROL_MISSING
ConstantLDAP_NAMING_VIOLATION
ConstantLDAP_OBJECT_CLASS_VIOLATION
ConstantLDAP_NOT_ALLOWED_ON_NONLEAF
ConstantLDAP_NOT_ALLOWED_ON_RDN
ConstantLDAP_ALREADY_EXISTS
ConstantLDAP_NO_OBJECT_CLASS_MODS
ConstantLDAP_RESULTS_TOO_LARGE
ConstantLDAP_AFFECTS_MULTIPLE_DSAS
ConstantLDAP_OTHER

constantint Protocols.LDAP.LDAP_SUCCESS
constantint Protocols.LDAP.LDAP_OPERATIONS_ERROR
constantint Protocols.LDAP.LDAP_PROTOCOL_ERROR
constantint Protocols.LDAP.LDAP_TIMELIMIT_EXCEEDED
constantint Protocols.LDAP.LDAP_SIZELIMIT_EXCEEDED
constantint Protocols.LDAP.LDAP_COMPARE_FALSE
constantint Protocols.LDAP.LDAP_COMPARE_TRUE
constantint Protocols.LDAP.LDAP_AUTH_METHOD_NOT_SUPPORTED
constant Protocols.LDAP.LDAP_STRONG_AUTH_NOT_SUPPORTED
constantint Protocols.LDAP.LDAP_STRONG_AUTH_REQUIRED
constantint Protocols.LDAP.LDAP_PARTIAL_RESULTS
constantint Protocols.LDAP.LDAP_REFERRAL
constantint Protocols.LDAP.LDAP_ADMINLIMIT_EXCEEDED
constantint Protocols.LDAP.LDAP_UNAVAILABLE_CRITICAL_EXTENSION
constantint Protocols.LDAP.LDAP_CONFIDENTIALITY_REQUIRED
constantint Protocols.LDAP.LDAP_SASL_BIND_IN_PROGRESS
constantint Protocols.LDAP.LDAP_NO_SUCH_ATTRIBUTE
constantint Protocols.LDAP.LDAP_UNDEFINED_TYPE
constantint Protocols.LDAP.LDAP_INAPPROPRIATE_MATCHING
constantint Protocols.LDAP.LDAP_CONSTRAINT_VIOLATION
constantint Protocols.LDAP.LDAP_TYPE_OR_VALUE_EXISTS
constantint Protocols.LDAP.LDAP_INVALID_SYNTAX
constantint Protocols.LDAP.LDAP_NO_SUCH_OBJECT
constantint Protocols.LDAP.LDAP_ALIAS_PROBLEM
constantint Protocols.LDAP.LDAP_INVALID_DN_SYNTAX
constantint Protocols.LDAP.LDAP_IS_LEAF
constantint Protocols.LDAP.LDAP_ALIAS_DEREF_PROBLEM
constantint Protocols.LDAP.LDAP_INAPPROPRIATE_AUTH
constantint Protocols.LDAP.LDAP_INVALID_CREDENTIALS
constantint Protocols.LDAP.LDAP_INSUFFICIENT_ACCESS
constantint Protocols.LDAP.LDAP_BUSY
constantint Protocols.LDAP.LDAP_UNAVAILABLE
constantint Protocols.LDAP.LDAP_UNWILLING_TO_PERFORM
constantint Protocols.LDAP.LDAP_LOOP_DETECT
constantint Protocols.LDAP.LDAP_SORT_CONTROL_MISSING
constantint Protocols.LDAP.LDAP_NAMING_VIOLATION
constantint Protocols.LDAP.LDAP_OBJECT_CLASS_VIOLATION
constantint Protocols.LDAP.LDAP_NOT_ALLOWED_ON_NONLEAF
constantint Protocols.LDAP.LDAP_NOT_ALLOWED_ON_RDN
constantint Protocols.LDAP.LDAP_ALREADY_EXISTS
constantint Protocols.LDAP.LDAP_NO_OBJECT_CLASS_MODS
constantint Protocols.LDAP.LDAP_RESULTS_TOO_LARGE
constantint Protocols.LDAP.LDAP_AFFECTS_MULTIPLE_DSAS
constantint Protocols.LDAP.LDAP_OTHER

Description

LDAP result codes.

See also

Protocols.LDAP.client.error_number, Protocols.LDAP.client.result.error_number


ConstantLDAP_CONTROL_MANAGE_DSA_IT

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


ConstantLDAP_CONTROL_VLVREQUEST

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


ConstantLDAP_CONTROL_VLVRESPONSE

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


ConstantLDAP_PAGED_RESULT_OID_STRING

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


ConstantLDAP_SERVER_ASQ_OID

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


ConstantLDAP_SERVER_CROSSDOM_MOVE_TARGET_OID

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


ConstantLDAP_SERVER_DIRSYNC_OID

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


ConstantLDAP_SERVER_DOMAIN_SCOPE_OID

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


ConstantLDAP_SERVER_EXTENDED_DN_OID

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


ConstantLDAP_SERVER_LAZY_COMMIT_OID

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


ConstantLDAP_SERVER_NOTIFICATION_OID

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


ConstantLDAP_SERVER_PERMISSIVE_MODIFY_OID

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


ConstantLDAP_SERVER_QUOTA_CONTROL_OID

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


ConstantLDAP_SERVER_RESP_SORT_OID

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


ConstantLDAP_SERVER_SD_FLAGS_OID

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


ConstantLDAP_SERVER_SEARCH_OPTIONS_OID

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


ConstantLDAP_SERVER_SHOW_DELETED_OID

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


ConstantLDAP_SERVER_SORT_OID

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


ConstantLDAP_SERVER_TREE_DELETE_OID

constantstring Protocols.LDAP.LDAP_SERVER_TREE_DELETE_OID

Description

LDAP control: Microsoft AD: Control used to delete an entire subtree in the directory.


ConstantLDAP_SERVER_VERIFY_NAME_OID

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


ConstantMODIFY_ADD
ConstantMODIFY_DELETE
ConstantMODIFY_REPLACE

constantint Protocols.LDAP.MODIFY_ADD
constantint Protocols.LDAP.MODIFY_DELETE
constantint Protocols.LDAP.MODIFY_REPLACE

Description

Constants used in the attropval argument to Protocols.LDAP.client.modify.


ConstantSCOPE_BASE
ConstantSCOPE_ONE
ConstantSCOPE_SUB

constantint Protocols.LDAP.SCOPE_BASE
constantint Protocols.LDAP.SCOPE_ONE
constantint 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).


ConstantSEARCH_LOWER_ATTRS
ConstantSEARCH_MULTIVAL_ARRAYS_ONLY
ConstantSEARCH_RETURN_DECODE_ERRORS

constantint Protocols.LDAP.SEARCH_LOWER_ATTRS
constantint Protocols.LDAP.SEARCH_MULTIVAL_ARRAYS_ONLY
constantint 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.


ConstantSYNTAX_AD_CASE_IGNORE_STR
ConstantSYNTAX_AD_LARGE_INT
ConstantSYNTAX_AD_OBJECT_SECURITY_DESCRIPTOR

constantstring Protocols.LDAP.SYNTAX_AD_CASE_IGNORE_STR
constantstring Protocols.LDAP.SYNTAX_AD_LARGE_INT
constantstring 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>.


ConstantSYNTAX_ATTR_TYPE_DESCR
ConstantSYNTAX_BINARY
ConstantSYNTAX_BIT_STRING
ConstantSYNTAX_BOOLEAN
ConstantSYNTAX_CERT
ConstantSYNTAX_CERT_LIST
ConstantSYNTAX_CERT_PAIR
ConstantSYNTAX_COUNTRY_STR
ConstantSYNTAX_DN
ConstantSYNTAX_DIRECTORY_STR
ConstantSYNTAX_DIT_CONTENT_RULE_DESCR
ConstantSYNTAX_FACSIMILE_PHONE_NUM
ConstantSYNTAX_FAX
ConstantSYNTAX_GENERALIZED_TIME
ConstantSYNTAX_IA5_STR
ConstantSYNTAX_INT
ConstantSYNTAX_JPEG
ConstantSYNTAX_MATCHING_RULE_DESCR
ConstantSYNTAX_MATCHING_RULE_USE_DESCR
ConstantSYNTAX_MHS_OR_ADDR
ConstantSYNTAX_NAME_AND_OPTIONAL_UID
ConstantSYNTAX_NAME_FORM_DESCR
ConstantSYNTAX_NUMERIC_STRING
ConstantSYNTAX_OBJECT_CLASS_DESCR
ConstantSYNTAX_OID
ConstantSYNTAX_OTHER_MAILBOX
ConstantSYNTAX_POSTAL_ADDR
ConstantSYNTAX_PRESENTATION_ADDR
ConstantSYNTAX_PRINTABLE_STR
ConstantSYNTAX_PHONE_NUM
ConstantSYNTAX_UTC_TIME
ConstantSYNTAX_LDAP_SYNTAX_DESCR
ConstantSYNTAX_DIT_STRUCTURE_RULE_DESCR

constantstring Protocols.LDAP.SYNTAX_ATTR_TYPE_DESCR
constantstring Protocols.LDAP.SYNTAX_BINARY
constantstring Protocols.LDAP.SYNTAX_BIT_STRING
constantstring Protocols.LDAP.SYNTAX_BOOLEAN
constantstring Protocols.LDAP.SYNTAX_CERT
constantstring Protocols.LDAP.SYNTAX_CERT_LIST
constantstring Protocols.LDAP.SYNTAX_CERT_PAIR
constantstring Protocols.LDAP.SYNTAX_COUNTRY_STR
constantstring Protocols.LDAP.SYNTAX_DN
constantstring Protocols.LDAP.SYNTAX_DIRECTORY_STR
constantstring Protocols.LDAP.SYNTAX_DIT_CONTENT_RULE_DESCR
constantstring Protocols.LDAP.SYNTAX_FACSIMILE_PHONE_NUM
constantstring Protocols.LDAP.SYNTAX_FAX
constantstring Protocols.LDAP.SYNTAX_GENERALIZED_TIME
constantstring Protocols.LDAP.SYNTAX_IA5_STR
constantstring Protocols.LDAP.SYNTAX_INT
constantstring Protocols.LDAP.SYNTAX_JPEG
constantstring Protocols.LDAP.SYNTAX_MATCHING_RULE_DESCR
constantstring Protocols.LDAP.SYNTAX_MATCHING_RULE_USE_DESCR
constantstring Protocols.LDAP.SYNTAX_MHS_OR_ADDR
constantstring Protocols.LDAP.SYNTAX_NAME_AND_OPTIONAL_UID
constantstring Protocols.LDAP.SYNTAX_NAME_FORM_DESCR
constantstring Protocols.LDAP.SYNTAX_NUMERIC_STRING
constantstring Protocols.LDAP.SYNTAX_OBJECT_CLASS_DESCR
constantstring Protocols.LDAP.SYNTAX_OID
constantstring Protocols.LDAP.SYNTAX_OTHER_MAILBOX
constantstring Protocols.LDAP.SYNTAX_POSTAL_ADDR
constantstring Protocols.LDAP.SYNTAX_PRESENTATION_ADDR
constantstring Protocols.LDAP.SYNTAX_PRINTABLE_STR
constantstring Protocols.LDAP.SYNTAX_PHONE_NUM
constantstring Protocols.LDAP.SYNTAX_UTC_TIME
constantstring Protocols.LDAP.SYNTAX_LDAP_SYNTAX_DESCR
constantstring Protocols.LDAP.SYNTAX_DIT_STRUCTURE_RULE_DESCR

Description

LDAP syntax: Standard syntaxes from RFC 2252.


ConstantSYNTAX_CASE_EXACT_STR

constant Protocols.LDAP.SYNTAX_CASE_EXACT_STR

Description

"caseExactString" is an alias used in e.g. RFC 2079.


ConstantSYNTAX_DELIVERY_METHOD
ConstantSYNTAX_ENHANCED_GUIDE
ConstantSYNTAX_GUIDE
ConstantSYNTAX_OCTET_STR
ConstantSYNTAX_TELETEX_TERMINAL_ID
ConstantSYNTAX_TELETEX_NUM
ConstantSYNTAX_SUPPORTED_ALGORITHM

constantstring Protocols.LDAP.SYNTAX_DELIVERY_METHOD
constantstring Protocols.LDAP.SYNTAX_ENHANCED_GUIDE
constantstring Protocols.LDAP.SYNTAX_GUIDE
constantstring Protocols.LDAP.SYNTAX_OCTET_STR
constantstring Protocols.LDAP.SYNTAX_TELETEX_TERMINAL_ID
constantstring Protocols.LDAP.SYNTAX_TELETEX_NUM
constantstring Protocols.LDAP.SYNTAX_SUPPORTED_ALGORITHM

Description

LDAP syntax: Standard syntaxes from RFC 2256.


Methodcanonicalize_dn

stringcanonicalize_dn(stringdn, void|intstrict)

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.


Methodencode_dn_value

stringencode_dn_value(stringstr)

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.


Methodget_cached_filter

objectget_cached_filter(stringfilter, void|intldap_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.


Methodget_connection

objectget_connection(stringldap_url, void|stringbinddn, void|stringpassword, void|intversion, void|SSL.Contextctx)

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.


Methodget_constant_name

stringget_constant_name(mixedval)

Description

If val matches any non-integer constant in this module, its name is returned.


Methodldap_decode_string

stringldap_decode_string(stringstr)

Description

Decodes all \xx escapes in str.

See also

ldap_encode_string


Methodldap_encode_string

stringldap_encode_string(stringstr)

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


Constantldap_error_strings

constant Protocols.LDAP.ldap_error_strings

Description

Mapping from LDAP_* result codes to descriptive strings.


Methodmake_filter

objectmake_filter(stringfilter, void|intldap_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.


Methodnum_connections

intnum_connections(stringldap_url)

Description

Returns the number of currently stored connections for the given LDAP URL.


Methodparse_ldap_url

mapping(string:mixed) parse_ldap_url(stringldap_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


Methodreturn_connection

voidreturn_connection(objectconn)

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


Constantsyntax_decode_fns

constantmapping(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.


Constantsyntax_encode_fns

constantmapping(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.


Constantis_ldap_filter_error

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


Methodadd

intadd(stringdn, 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.


Methodbind

intbind()
intbind(stringdn, stringpassword)
intbind(stringdn, stringpassword, intversion)

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.


Methodcompare

intcompare(stringdn, stringattr, stringvalue)

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.


Methodcreate

Protocols.LDAP.clientProtocols.LDAP.client()
Protocols.LDAP.clientProtocols.LDAP.client(string|mapping(string:mixed) url)
Protocols.LDAP.clientProtocols.LDAP.client(string|mapping(string:mixed) url, objectcontext)

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


Methoddelete

intdelete(stringdn)

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.


Methodget_attr_type_descr

mapping(string:mixed) get_attr_type_descr(stringattr, void|intstandard_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.


Methodget_basedn

stringget_basedn()

Description

Returns the current base DN for searches using search and schema queries using get_attr_type_descr.


Methodget_bind_password_hash

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


Methodget_bound_dn

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


Methodget_cached_filter

objectget_cached_filter(stringfilter)

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.


Methodget_default_filter

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


Methodget_option

intget_option(intopttype)

Parameter option_type

LDAP_OPT_xxx


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


Methodget_protocol_version

intget_protocol_version()

Description

Return the LDAP protocol version in use.


Methodget_referrals

array|intget_referrals()

Description

Gets referrals.

Returns

Returns array of referrals or 0.


Methodget_root_dse_attr

array(string) get_root_dse_attr(stringattr)

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.


Methodget_scope

stringget_scope()

Description

Return the currently set scope as a string "base", "one", or "sub".


Methodget_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


Variableinfo

mapping Protocols.LDAP.client.info

Description

Several information about code itself and about active connection too


Inheritprotocol

inherit .protocol : protocol


Methodmake_filter

objectmake_filter(stringfilter)

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.


Methodmodify

intmodify(stringdn, 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<span class='delim'>=</span><span class='delim'>(</span><span class='delim'>[</span> attribute<span class='delim'>:</span> <span class='delim'>(</span><span class='delim'>{</span>operation<span class='delim'>,</span> value1<span class='delim'>,</span> value2<span class='delim'>,</span> ...<span class='delim'>}</span><span class='delim'>)</span> <span class='delim'>]</span><span class='delim'>)</span>

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.


Methodmodifydn

intmodifydn(stringdn, stringnewrdn, intdeleteoldrdn, string|voidnewsuperior)

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.


Methodparse_url

mapping(string:mixed) parse_url(stringldapuri)

Description

Compatibility alias for Protocols.LDAP.parse_ldap_url.


Methodread

mapping(string:string|array(string)) read(stringobject_name, void|stringfilter, void|array(string) attrs, void|intattrsonly, void|mapping(string:array(int|string)) controls, void|intflags)

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


Methodread_attr

string|array(string) read_attr(stringobject_name, stringattr, void|stringfilter, 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


Methodreset_options

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


Methodsearch

result|intsearch(string|object|voidfilter, array(string)|voidattrs, int|voidattrsonly, void|mapping(string:array(int|string)) controls, void|intflags)

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
int0

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


Methodset_basedn

stringset_basedn(stringbase_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.


Methodset_option

intset_option(intopttype, intvalue)

Parameter option_type

LDAP_OPT_xxx

Parameter value

new value for option


Methodset_scope

intset_scope(int|stringscope)

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.


Methodstart_tls

intstart_tls(void|SSL.Contextcontext)

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.


Methodunbind

intunbind()

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


Methodcount_entries

intcount_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


Methodcreate

Protocols.LDAP.client.resultProtocols.LDAP.client.result(array(object) entries, intstuff, intflags)

Description

You can't create instances of this object yourself. The only way to create it is via a search of a LDAP server.


Methoderror_number

interror_number()

Description

Returns the error number in the search result.

See also

error_string, server_error_string


Methoderror_string

stringerror_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


Methodfetch

ResultEntryfetch(int|voididx)

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


Methodfetch_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


Methodfirst

voidfirst()

Description

Initialized the result cursor to the first entry in the result list.

See also

LDAP.client.result.next


Methodget_dn

string|Charset.DecodeErrorget_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.


Methodnext

intnext()

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


Methodnum_entries

intnum_entries()

Description

Returns the number of entries.

See also

LDAP.client.result.count_entries


Methodserver_error_string

stringserver_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


Methoderror_number

interror_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


Methoderror_string

stringerror_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


Methodget_last_io_time

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


Methodserver_error_string

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


Methodcreate

Protocols.LMTP.ServerProtocols.LMTP.Server(array(string) _domains, void|intport, void|stringip, 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).


Methodcreate

Protocols.LPD.clientProtocols.LPD.client(string|voidhostname, int|voidportnum)

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.


Methoddelete_job

intdelete_job(stringqueue, int|voidjob)

Description

Delete job job from printer queue.

Returns

Returns 1 on success, 0 otherwise.


Methodsend_job

string|intsend_job(stringqueue, stringjob)

Description

Send print job consisting of data job to printer queue.

Returns

Returns 1 if success, 0 otherwise.


Methodset_job_name

intset_job_name(stringname)

Description

Sets the name of the print job to name.


Methodset_job_type

intset_job_type(stringtype)

Description

Set the type of job to be sent to the printer to type. Valid types are: text, postscript and raw.


Methodstart_queue

intstart_queue(stringqueue)

Description

Start the queue queue if not already printing.

Returns

Returns 0 if unable to connect, 1 otherwise.


Methodstatus

string|intstatus(stringqueue)

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.


Methodexpect_literal

voidexpect_literal(intlength, function(string:void) callback)

Description

Enter literal reading mode.

Sets literal_length and handle_literal().

See also

literal_length, handle_literal()


Methodhandle_command

voidhandle_command(stringline)

Description

Function called once for every received line.


Variablehandle_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()


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


Inheritsimple

inherit simple : simple


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


Methodclose_callback

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


Methodcreate

Protocols.Line.simpleProtocols.Line.simple(Stdio.Filecon, int|voidtimeout)

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


Methoddisconnect

voiddisconnect()

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.


Methoddo_timeout

protectedvoiddo_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()


Methodhandle_command

voidhandle_command(stringline)

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


Variablehandle_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()


Constantline_separator

protected constantstring Protocols.Line.simple.line_separator

Description

The sequence separating lines from eachother. "\r\n" by default.


Methodread_callback

protectedvoidread_callback(mixedignored, stringdata)

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


Methodread_line

protectedstringread_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


Methodsend

protectedvoidsend(strings)

Description

Queue some data to send.

See also

handle_command(), handle_data(), disconnect()


Variablesend_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()


Methodtouch_time

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


Variableerrorcodes

mapping(int:string|array(string)) Protocols.Line.smtp_style.errorcodes

Description

Mapping from return-code to error-message.

Overload this constant as apropriate.


Inheritsimple

inherit simple : simple


Methodsend

voidsend(int(100..999)code, array(string)|string|voidlines)

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


Methodcommand

voidcommand(stringcmd, function(:void)|voidcb)

Description

send a command to the server

Returns

the result code sent by the server


Inheritprotocolhelper

inherit protocolhelper : protocolhelper


Inheritsock

inherit Stdio.File : sock


Methodreadreturncode

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


Methodarticle

stringarticle(void|int|stringx)


Methodbody

stringbody(void|int|stringx)


Methodcreate

Protocols.NNTP.clientProtocols.NNTP.client(string|voidserver)

Parameter server

NNTP server to connect to. Defaults to the server specified by the environment variable NNTPSERVER.


Variablecurrent_group

Group Protocols.NNTP.client.current_group

Description

The current news group.


Methodgo_to_group

Groupgo_to_group(stringgroup)

Description

Sets the current group to group.


Methodhead

stringhead(void|int|stringx)


Inheritprotocol

inherit protocol : protocol


Methodlist_groups

array(Group) list_groups()

Description

Returns a list of all active groups.


Methodset_group

voidset_group(Groupo)

Description

Sets the current news group to o.

Class Protocols.NNTP.protocol

Description

Synchronous NNTP protocol


Methodcommand

intcommand(stringcmd)

Description

send a command to the server

Returns

the result code sent by the server


Methoddo_cmd_with_body

stringdo_cmd_with_body(stringcmd)

Description

send a command that should return a message body.

Returns

the message body


Methodfailsafe_command

intfailsafe_command(stringcmd)

Description

send a command and require an ok response (200 series). throws an error if the command result was not success.


Inheritprotocolhelper

inherit protocolhelper : protocolhelper


Inheritsock

inherit Stdio.FILE : sock


Methodread_body_lines

array(string) read_body_lines()

Description

reads the message from the server as an array of lines


Methodreadreturnbody

stringreadreturnbody()

Description

reads the message from the server


Methodreadreturncode

intreadreturncode()

Description

reads the server result code for last request used internally by command().


Methodwritebody

voidwritebody(strings)

Description

send the body of a message to the server.

Class Protocols.NNTP.protocolhelper

Description

helper class for protocol implementations.

See also

protocol


Methodget_response_message

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


TypedefHeaders

typedefmapping(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.


ConstantSETPATH_BACKUP

final constantint Protocols.OBEX.SETPATH_BACKUP

Description

A flag for the REQ_SETPATH command indicating that the parent directory should be selected


ConstantSETPATH_NOCREATE

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


Methoddecode_headers

Headersdecode_headers(stringh)

Description

Deserialize a set of headers from wire format


Methodencode_headers

stringencode_headers(Headersh)

Description

Serialize a set of headers to wire format

See also

split_headers()


Methodsplit_headers

array(string) split_headers(stringh, intchunklen)

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


ConstantHI_APPPARAM

constant Protocols.OBEX.HI_APPPARAM

Description

Extended application request & response information


ConstantHI_AUTHCHALL

constant Protocols.OBEX.HI_AUTHCHALL

Description

Authentication digest-challenge


ConstantHI_AUTHRESP

constant Protocols.OBEX.HI_AUTHRESP

Description

Authentication digest-response


ConstantHI_BODY

constant Protocols.OBEX.HI_BODY

Description

A chunk of the object body


ConstantHI_CONNID

constant Protocols.OBEX.HI_CONNID

Description

An identifier used for OBEX connection multiplexing


ConstantHI_COUNT

constant Protocols.OBEX.HI_COUNT

Description

Number of objects to transfer (used by REQ_CONNECT)


ConstantHI_CREATORID

constant Protocols.OBEX.HI_CREATORID

Description

Indicates the creator of an object


ConstantHI_DESCRIPTION

constant Protocols.OBEX.HI_DESCRIPTION

Description

Text description of the object


ConstantHI_ENDOFBODY

constant Protocols.OBEX.HI_ENDOFBODY

Description

The final chunk of the object body


ConstantHI_HTTP

constant Protocols.OBEX.HI_HTTP

Description

Any HTTP 1.x header


ConstantHI_LENGTH

constant Protocols.OBEX.HI_LENGTH

Description

Length of the object transferred, in octets


ConstantHI_NAME

constant Protocols.OBEX.HI_NAME

Description

Name of the object (string)


ConstantHI_OBJCLASS

constant Protocols.OBEX.HI_OBJCLASS

Description

OBEX object class of object


ConstantHI_SESSPARAM

constant Protocols.OBEX.HI_SESSPARAM

Description

Parameters used in session commands/responses


ConstantHI_SESSSEQNR

constant Protocols.OBEX.HI_SESSSEQNR

Description

Sequence number used in each OBEX packet for reliability


ConstantHI_TARGET

constant Protocols.OBEX.HI_TARGET

Description

Name of service that operation is targeted to


ConstantHI_TIME

constant Protocols.OBEX.HI_TIME

Description

ISO 8601 timestamp (string)


ConstantHI_TYPE

constant Protocols.OBEX.HI_TYPE

Description

Type of the object (IANA media type)


ConstantHI_WANUUID

constant Protocols.OBEX.HI_WANUUID

Description

Uniquely identifies the OBEX server


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


ConstantREQ_ABORT

constant Protocols.OBEX.REQ_ABORT

Description

Abort the request currently being processed


ConstantREQ_CONNECT

constant Protocols.OBEX.REQ_CONNECT

Description

Establish a new OBEX connection


ConstantREQ_DISCONNECT

constant Protocols.OBEX.REQ_DISCONNECT

Description

Terminate an OBEX connection


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


ConstantREQ_GET

constant Protocols.OBEX.REQ_GET

Description

Receive an object from the mobile devuce


ConstantREQ_PUT

constant Protocols.OBEX.REQ_PUT

Description

Send an object to the mobile device


ConstantREQ_SESSION

constant Protocols.OBEX.REQ_SESSION

Description

Manage a session


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


InheritClient

inherit Client : Client

Class Protocols.OBEX.Client

Description

An OBEX client

See also

ATclient


Methodconnect

boolconnect()

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.


Methodcreate

Protocols.OBEX.ClientProtocols.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.


Methoddisconnect

booldisconnect()

Description

Terminate a connection using the REQ_DISCONNECT opcode

Returns

If the disconnection succeeds, 1 is returned. Otherwise, 0 is returned.


Methoddo_abort

array(int|Headers) do_abort(Headers|voidheaders)

Description

Perform a REQ_ABORT request.

See also

do_request()


Methoddo_get

array(int|Headers) do_get(Stdio.Streamdata, Headers|voidheaders)

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


Methoddo_put

array(int|Headers) do_put(string|Stdio.Streamdata, Headers|voidextra_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()


Methoddo_request

array(int|Headers) do_request(Requestr, Headers|voidheaders, string|voidextra_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
intreturncode

An HTTP response code

Headersheaders

Response headers

See also

low_do_request(), do_abort(), do_put(), do_get(), do_setpath(), do_session()


Methoddo_session

array(int|Headers) do_session(Headers|voidheaders)

Description

Perform a REQ_SESSION request.

See also

do_request()


Methoddo_setpath

array(int|Headers) do_setpath(stringpath, int|voidflags, Headers|voidextra_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()


Methodlow_do_request

array(int|string) low_do_request(Requestr, stringdata)

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
intreturncode

An HTTP response code

stringdata

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`[](stringname)

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


Methodlookup

array(Service) lookup(stringname)

Description

Return all ports registered for the specified name This function also reads data from /etc/services if possible.


Methodport

intport(stringname)

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)


Constantprivate_tcp

constant Protocols.Ports.private_tcp

Description

Contains all TCP ports assigned for private use as of RFC 1700


Constantprivate_udp

constant Protocols.Ports.private_udp

Description

Contains all UDP ports assigned for private use as of RFC 1700


Constanttcp

constant Protocols.Ports.tcp

Description

Contains all non-private TCP port assignments as of RFC 1700 Extended with some non-official.


Constantudp

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.


Variablename
Variableport
Variableprotocol
Variablecomment

string Protocols.Ports.Service.name
int Protocols.Ports.Service.port
string Protocols.Ports.Service.protocol
string Protocols.Ports.Service.comment


Methodcreate

Protocols.Ports.ServiceProtocols.Ports.Service(stringname, intport, stringprotocol, stringcomment)

Module Protocols.SMTP


Variablereplycodes

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


Methodcreate

Protocols.SMTP.AsyncClientProtocols.SMTP.AsyncClient(void|string|objectserver, int|voidport, function(:void)|voidcb, 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.


InheritAsyncProtocol

inherit AsyncProtocol : AsyncProtocol


InheritClientHelper

inherit ClientHelper : ClientHelper


Methodsend_message

voidsend_message(stringfrom, array(string) to, stringbody, function(:void)|voidcb, 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


Methodsimple_mail

voidsimple_mail(stringto, stringsubject, stringfrom, stringmsg, function(:void)|voidcb, 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.


Methodverify

voidverify(stringaddr, 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
intcode

The numerical return code from the VRFY call.

stringmessage

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


Methodcreate

Protocols.SMTP.ClientProtocols.SMTP.Client()
Protocols.SMTP.ClientProtocols.SMTP.Client(Stdio.Fileserver)
Protocols.SMTP.ClientProtocols.SMTP.Client(stringserver, void|intport)

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.


InheritClientHelper

inherit ClientHelper : ClientHelper


InheritProtocol

inherit Protocol : Protocol


Methodsend_message

voidsend_message(stringfrom, array(string) to, stringbody)

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.


Methodsimple_mail

voidsimple_mail(stringto, stringsubject, stringfrom, stringmsg)

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.


Methodverify

array(int|string) verify(stringaddr)

Description

Verifies the mail address addr against the mail server.

Returns
Array
intcode

The numerical return code from the VRFY call.

stringmessage

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.


Methodparse_addr

protectedstringparse_addr(stringaddr)

Description

Parses email addresses as the Protocols.SMTP client classes do. Useful if emails should only be sent matching certain conditions etc..


Methodrfc2822date_time

stringrfc2822date_time(intts)

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


Variablecheckdns

int Protocols.SMTP.Configuration.checkdns

Description

Verify sender domain for MX


Variablecheckemail

int Protocols.SMTP.Configuration.checkemail

Description

Lamme check email from validity


Variablegivedata

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


Variablemaxrcpt

int Protocols.SMTP.Configuration.maxrcpt

Description

Maximum number of recipients (default 1000)


Variablemaxsize

int Protocols.SMTP.Configuration.maxsize

Description

Message max size

Class Protocols.SMTP.Connection

Description

The low-level class for the SMTP server


Variablelogfunction

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


Methodcreate

Protocols.SMTP.ServerProtocols.SMTP.Server(array(string) _domains, void|intport, void|stringip, 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


ConstantERROR_BADVALUE

constant Protocols.SNMP.ERROR_BADVALUE

Description

Error badValue


ConstantERROR_GENERROR

constant Protocols.SNMP.ERROR_GENERROR

Description

Error genError


ConstantERROR_NOERROR

constant Protocols.SNMP.ERROR_NOERROR

Description

Error noError


ConstantERROR_NOSUCHNAME

constant Protocols.SNMP.ERROR_NOSUCHNAME

Description

Error noSuchName


ConstantERROR_READONLY

constant Protocols.SNMP.ERROR_READONLY

Description

Error readOnly


ConstantERROR_TOOBIG

constant Protocols.SNMP.ERROR_TOOBIG

Description

Error tooBig


ConstantREQUEST_GET

constant Protocols.SNMP.REQUEST_GET

Description

PDU type Get


ConstantREQUEST_GETNEXT

constant Protocols.SNMP.REQUEST_GETNEXT

Description

PDU type GetNext


ConstantREQUEST_GET_RESPONSE

constant Protocols.SNMP.REQUEST_GET_RESPONSE

Description

PDU type GetResponse


ConstantREQUEST_SET

constant Protocols.SNMP.REQUEST_SET

Description

PDU type Set


ConstantREQUEST_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


Methodclear_get_oid_callback

intclear_get_oid_callback(stringoid)

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


Methodclear_set_oid_callback

intclear_set_oid_callback(stringoid)

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


Methodcreate

Protocols.SNMP.agentProtocols.SNMP.agent(int|voidport, string|voidaddr)

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.


Methodget_get_oid_callback

void|function(:void) get_get_oid_callback(stringoid)

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


Methodget_set_oid_callback

void|function(:void) get_set_oid_callback(stringoid)

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"


Methodset_get_communities

voidset_get_communities(arraycommunities)

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


Methodset_get_oid_callback

voidset_get_oid_callback(stringoid, 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.


Methodset_managers

voidset_managers(arraymanagers)

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


Methodset_managers_only

voidset_managers_only(intyesno)

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


Methodset_set_communities

voidset_set_communities(arraycommunities)

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


Methodset_set_oid_callback

voidset_set_oid_callback(stringoid, 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.


Methodset_threaded

voidset_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


Methodcreate

Protocols.SNMP.protocolProtocols.SNMP.protocol(int|voidrem_port, string|voidrem_addr, int|voidloc_port, string|voidloc_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)


Methoddecode_asn1_msg

mappingdecode_asn1_msg(mappingrawd)

Description

decode ASN1 data, if garbaged ignore it


Methodget_nextrequest

intget_nextrequest(array(string) varlist, string|voidrem_addr, int|voidrem_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


Methodget_request

intget_request(array(string) varlist, string|voidrem_addr, int|voidrem_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


Methodget_response

intget_response(mappingvarlist, mappingorigdata, int|voiderrcode, int|voiderridx)

Description

GetResponse-PDU call

Parameter varlist

a mapping containing data to return

oid1 : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

data to return for oid1

oid2 : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

data to return for oid2

oidn : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

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


Inheritsnmp

inherit Stdio.UDP : snmp


Methodreadmsg

mappingreadmsg(int|float|voidtimeout)

Description

return the whole SNMP message in raw format


Methodreadmsg_from_pool

privatemappingreadmsg_from_pool(intmsgid)

Description

read decoded message from pool


Methodset_request

intset_request(mappingvarlist, string|voidrem_addr, int|voidrem_port)

Description

SetRequest-PDU call

Parameter varlist

a mapping of OIDs to SET

oid1 : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

data to return for oid1

oid2 : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

data to return for oid2

oidn : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

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");


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


Variablesnmp_version

int Protocols.SNMP.protocol.snmp_version

Description

SNMP version

currently version 1 and 2 are supported.


Methodto_pool

voidto_pool(mappingrawd)

Description

decode raw pdu message and place in message pool


Methodtrap

inttrap(mappingvarlist, stringoid, inttype, intspectype, intticks, string|voidlocip, string|voidremaddr, int|voidremport)

Description

send an SNMP-v1 trap

Parameter varlist

a mapping of OIDs to include in trap

oid1 : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

data to return for oid1

oid2 : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

data to return for oid2

oidn : array
Array
stringtype

data type such as tick, oid, gauge, etc

mixeddata

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.


ConstantAUTH_WHO_CLIENT

constantint Protocols.TELNET.AUTH_WHO_CLIENT

Description

Client authenticating server


ConstantAUTH_WHO_SERVER

constantint Protocols.TELNET.AUTH_WHO_SERVER

Description

Server authenticating client


ConstantLFLOW_OFF

constantint Protocols.TELNET.LFLOW_OFF

Description

Disable remote flow control


ConstantLFLOW_ON

constantint Protocols.TELNET.LFLOW_ON

Description

Enable remote flow control


ConstantLFLOW_RESTART_ANY

constantint Protocols.TELNET.LFLOW_RESTART_ANY

Description

Restart output on any char


ConstantLFLOW_RESTART_XON

constantint Protocols.TELNET.LFLOW_RESTART_XON

Description

Restart output only on XON


ConstantTELQUAL_INFO

constantint Protocols.TELNET.TELQUAL_INFO

Description

ENVIRON: informational version of IS


ConstantTELQUAL_IS

constantint Protocols.TELNET.TELQUAL_IS

Description

option is...


ConstantTELQUAL_NAME

constantint Protocols.TELNET.TELQUAL_NAME

Description

AUTHENTICATION: client version of IS


ConstantTELQUAL_REPLY

constantint Protocols.TELNET.TELQUAL_REPLY

Description

AUTHENTICATION: client version of IS


ConstantTELQUAL_SEND

constantint Protocols.TELNET.TELQUAL_SEND

Description

send option


InheritTelnetCodes

inherit TelnetCodes : TelnetCodes


InheritTelopts

inherit Telopts : Telopts

Class Protocols.TELNET.LineMode

Description

Line-oriented TELNET protocol handler.


Inheritprotocol

inherit protocol : protocol

Description

Based on the generic TELNET protocol handler.


Methodsetup

protectedvoidsetup()

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.


Methodclose

voidclose()

Description

Close the connection.


Methodcreate

Protocols.TELNET.ReadlineProtocols.TELNET.Readline(objectf, function(mixed, string:void) r_cb, function(mixed|void:string) w_cb, function(mixed|void:void) c_cb, mappingcallbacks, mixed|voidnew_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.


InheritLineMode

inherit LineMode : LineMode

Description

Based on the Line-oriented TELNET protocol handler.


Methodmessage

voidmessage(strings, void|intword_wrap)

Description

Write a message.


Methodquery_close_callback

function(mixed|void:void) query_close_callback()


Methodquery_read_callback

function(mixed, string:void) query_read_callback()


Methodquery_write_callback

function(mixed|void:string) query_write_callback()


Variablereadline

Stdio.Readline Protocols.TELNET.Readline.readline

Description

Stdio.Readline object handling the connection.


Methodset_blocking

voidset_blocking()


Methodset_close_callback

voidset_close_callback(function(mixed|void:void) c_cb)


Methodset_nonblocking

voidset_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()


Methodset_prompt

voidset_prompt(strings)

Description

Set the readline prompt.


Methodset_read_callback

voidset_read_callback(function(mixed, string:void) r_cb)


Methodset_secret

voidset_secret(intonoff)

Description

Turn on/off echo mode.


Methodset_write_callback

voidset_write_callback(function(mixed|void:string) w_cb)


Methodtcgetattr

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


Methodtcsetattr

inttcsetattr(mapping(string:int) options, string|voidwhen)

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


Methodwrite

voidwrite(strings)

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.


ConstantABORT

constantint Protocols.TELNET.TelnetCodes.ABORT

Description

Abort process


ConstantAO

constantint Protocols.TELNET.TelnetCodes.AO

Description

abort output--but let prog finish


ConstantAYT

constantint Protocols.TELNET.TelnetCodes.AYT

Description

are you there


ConstantBREAK

constantint Protocols.TELNET.TelnetCodes.BREAK

Description

break


ConstantDM

constantint Protocols.TELNET.TelnetCodes.DM

Description

data mark--for connect. cleaning


ConstantDO

constantint Protocols.TELNET.TelnetCodes.DO

Description

please, you use option


ConstantDONT

constantint Protocols.TELNET.TelnetCodes.DONT

Description

you are not to use option


ConstantEC

constantint Protocols.TELNET.TelnetCodes.EC

Description

erase the current character


ConstantEL

constantint Protocols.TELNET.TelnetCodes.EL

Description

erase the current line


ConstantEOR

constantint Protocols.TELNET.TelnetCodes.EOR

Description

end of record (transparent mode)


ConstantGA

constantint Protocols.TELNET.TelnetCodes.GA

Description

you may reverse the line


ConstantIAC

constantint Protocols.TELNET.TelnetCodes.IAC

Description

interpret as command.


ConstantIP

constantint Protocols.TELNET.TelnetCodes.IP

Description

interrupt process--permanently


ConstantNOP

constantint Protocols.TELNET.TelnetCodes.NOP

Description

nop


ConstantSB

constantint Protocols.TELNET.TelnetCodes.SB

Description

interpret as subnegotiation


ConstantSE

constantint Protocols.TELNET.TelnetCodes.SE

Description

end sub negotiation


ConstantSUSP

constantint Protocols.TELNET.TelnetCodes.SUSP

Description

Suspend process


ConstantSYNCH

constantint Protocols.TELNET.TelnetCodes.SYNCH

Description

for telfunc calls


ConstantWILL

constantint Protocols.TELNET.TelnetCodes.WILL

Description

I will use option


ConstantWONT

constantint Protocols.TELNET.TelnetCodes.WONT

Description

I won't use option


ConstantxEOF

constantint Protocols.TELNET.TelnetCodes.xEOF

Description

End of file: EOF is already used...

Class Protocols.TELNET.Telopts

Description

Table of TELNET options.


ConstantTELOPT_3270REGIME

constantint Protocols.TELNET.Telopts.TELOPT_3270REGIME

Description

3270 regime


ConstantTELOPT_AUTHENTICATION

constantint Protocols.TELNET.Telopts.TELOPT_AUTHENTICATION

Description

Authenticate


ConstantTELOPT_BINARY

constantint Protocols.TELNET.Telopts.TELOPT_BINARY

Description

8-bit data path


ConstantTELOPT_BM

constantint Protocols.TELNET.Telopts.TELOPT_BM

Description

byte macro


ConstantTELOPT_DET

constantint Protocols.TELNET.Telopts.TELOPT_DET

Description

data entry terminal


ConstantTELOPT_ECHO

constantint Protocols.TELNET.Telopts.TELOPT_ECHO

Description

echo


ConstantTELOPT_ENCRYPT

constantint Protocols.TELNET.Telopts.TELOPT_ENCRYPT

Description

Encryption option


ConstantTELOPT_EOR

constantint Protocols.TELNET.Telopts.TELOPT_EOR

Description

end or record


ConstantTELOPT_EXOPL

constantint Protocols.TELNET.Telopts.TELOPT_EXOPL

Description

extended-options-list


ConstantTELOPT_LFLOW

constantint Protocols.TELNET.Telopts.TELOPT_LFLOW

Description

remote flow control


ConstantTELOPT_LINEMODE

constantint Protocols.TELNET.Telopts.TELOPT_LINEMODE

Description

Linemode option


ConstantTELOPT_LOGOUT

constantint Protocols.TELNET.Telopts.TELOPT_LOGOUT

Description

force logout


ConstantTELOPT_NAMS

constantint Protocols.TELNET.Telopts.TELOPT_NAMS

Description

approximate message size


ConstantTELOPT_NAOCRD

constantint Protocols.TELNET.Telopts.TELOPT_NAOCRD

Description

negotiate about CR disposition


ConstantTELOPT_NAOFFD

constantint Protocols.TELNET.Telopts.TELOPT_NAOFFD

Description

negotiate about formfeed disposition


ConstantTELOPT_NAOHTD

constantint Protocols.TELNET.Telopts.TELOPT_NAOHTD

Description

negotiate about horizontal tab disposition


ConstantTELOPT_NAOHTS

constantint Protocols.TELNET.Telopts.TELOPT_NAOHTS

Description

negotiate about horizontal tabstops


ConstantTELOPT_NAOL

constantint Protocols.TELNET.Telopts.TELOPT_NAOL

Description

negotiate about output line width


ConstantTELOPT_NAOLFD

constantint Protocols.TELNET.Telopts.TELOPT_NAOLFD

Description

negotiate about output LF disposition


ConstantTELOPT_NAOP

constantint Protocols.TELNET.Telopts.TELOPT_NAOP

Description

negotiate about output page size


ConstantTELOPT_NAOVTD

constantint Protocols.TELNET.Telopts.TELOPT_NAOVTD

Description

negotiate about vertical tab disposition


ConstantTELOPT_NAOVTS

constantint Protocols.TELNET.Telopts.TELOPT_NAOVTS

Description

negotiate about vertical tab stops


ConstantTELOPT_NAWS

constantint Protocols.TELNET.Telopts.TELOPT_NAWS

Description

window size


ConstantTELOPT_NEW_ENVIRON

constantint Protocols.TELNET.Telopts.TELOPT_NEW_ENVIRON

Description

New - Environment variables


ConstantTELOPT_OLD_ENVIRON

constantint Protocols.TELNET.Telopts.TELOPT_OLD_ENVIRON

Description

Old - Environment variables


ConstantTELOPT_OUTMRK

constantint Protocols.TELNET.Telopts.TELOPT_OUTMRK

Description

output marking


ConstantTELOPT_RCP

constantint Protocols.TELNET.Telopts.TELOPT_RCP

Description

prepare to reconnect


ConstantTELOPT_RCTE

constantint Protocols.TELNET.Telopts.TELOPT_RCTE

Description

remote controlled transmission and echo


ConstantTELOPT_SGA

constantint Protocols.TELNET.Telopts.TELOPT_SGA

Description

suppress go ahead


ConstantTELOPT_SNDLOC

constantint Protocols.TELNET.Telopts.TELOPT_SNDLOC

Description

send location


ConstantTELOPT_STATUS

constantint Protocols.TELNET.Telopts.TELOPT_STATUS

Description

give status


ConstantTELOPT_SUPDUP

constantint Protocols.TELNET.Telopts.TELOPT_SUPDUP

Description

supdup protocol


ConstantTELOPT_SUPDUPOUTPUT

constantint Protocols.TELNET.Telopts.TELOPT_SUPDUPOUTPUT

Description

supdup output


ConstantTELOPT_TM

constantint Protocols.TELNET.Telopts.TELOPT_TM

Description

timing mark


ConstantTELOPT_TSPEED

constantint Protocols.TELNET.Telopts.TELOPT_TSPEED

Description

terminal speed


ConstantTELOPT_TTYLOC

constantint Protocols.TELNET.Telopts.TELOPT_TTYLOC

Description

terminal location number


ConstantTELOPT_TTYPE

constantint Protocols.TELNET.Telopts.TELOPT_TTYPE

Description

terminal type


ConstantTELOPT_TUID

constantint Protocols.TELNET.Telopts.TELOPT_TUID

Description

TACACS user identification


ConstantTELOPT_X3PAD

constantint Protocols.TELNET.Telopts.TELOPT_X3PAD

Description

X.3 PAD


ConstantTELOPT_XASCII

constantint Protocols.TELNET.Telopts.TELOPT_XASCII

Description

extended ascic character set


ConstantTELOPT_XDISPLOC

constantint Protocols.TELNET.Telopts.TELOPT_XDISPLOC

Description

X Display Location

Class Protocols.TELNET.protocol

Description

Implementation of the TELNET protocol.


Methodcall_read_cb

protectedvoidcall_read_cb(stringdata)

Description

Calls read_cb().

Specifically provided for overloading


Variablecb

protectedmapping Protocols.TELNET.protocol.cb

Description

Mapping containing extra callbacks.


Methodclose

voidclose()

Description

Closes the connetion neatly


Variableclose_cb

protectedfunction(mixed|void:void) Protocols.TELNET.protocol.close_cb

Description

Close callback.


Methodcreate

Protocols.TELNET.protocolProtocols.TELNET.protocol(objectf, function(mixed, string:void) r_cb, function(mixed|void:string) w_cb, function(mixed|void:void) c_cb, mappingcallbacks, mixed|voidnew_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.


Methoddisable_write

protectedvoiddisable_write()

Description

Turns off the write callback if apropriate.


Variabledone

protectedint Protocols.TELNET.protocol.done

Description

Indicates that connection should be closed


Methodenable_write

protectedvoidenable_write()

Description

Turns on the write callback if apropriate.


Variablefd

protectedobject Protocols.TELNET.protocol.fd

Description

The connection.


Methodgot_data

protectedvoidgot_data(mixedignored, stringline)

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.


Methodgot_oob

protectedvoidgot_oob(mixedignored, strings)

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.


Variableid

protectedmixed Protocols.TELNET.protocol.id

Description

Value to send to the callbacks.


Variableremote_options
Variablelocal_options

protectedarray(int) Protocols.TELNET.protocol.remote_options
protectedarray(int) Protocols.TELNET.protocol.local_options

Description

Negotiation states of all WILL/WON'T options. See RFC 1143 for a description of the states.


Variablenonblocking_write

protectedint Protocols.TELNET.protocol.nonblocking_write

Description

Tells if we have set the nonblocking write callback or not.


Methodquery_close_callback

function(mixed|void:void) query_close_callback()


Methodquery_read_callback

function(mixed, string:void) query_read_callback()


Methodquery_write_callback

function(mixed|void:string) query_write_callback()


Variableread_cb

protectedfunction(mixed, string:void) Protocols.TELNET.protocol.read_cb

Description

Read callback.


Methodsend_DO

voidsend_DO(intoption)

Description

Starts negotiation to enable a TELNET option.

Parameter option

The option to enable.


Methodsend_DONT

voidsend_DONT(intoption)

Description

Starts negotiation to disable a TELNET option.

Parameter option

The option to disable.


Methodsend_data

protectedvoidsend_data()

Description

Callback called when it is clear to send data over the connection. This function does the actual sending.


Methodsend_synch

voidsend_synch()

Description

Sends a TELNET synch command.


Methodset_close_callback

voidset_close_callback(function(mixed|void:void) c_cb)


Methodset_nonblocking

voidset_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()


Methodset_read_callback

voidset_read_callback(function(mixed, string:void) r_cb)


Methodset_write_callback

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


Methodsetup

protectedvoidsetup()

Description

Called when the initial setup is done.

Created specifically for overloading


Variablesynch

protectedint Protocols.TELNET.protocol.synch

Description

Indicates whether we are in synch-mode or not.


Variableto_send

protectedstring Protocols.TELNET.protocol.to_send

Description

Data queued to be sent.


Methodwrite

voidwrite(strings)

Description

Queues data to be sent to the other end of the connection.

Parameter s

String to send.


Variablewrite_cb

protectedfunction(mixed|void:string) Protocols.TELNET.protocol.write_cb

Description

Write callback.


Methodwrite_raw

voidwrite_raw(strings)

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.


ConstantCLOSE_BAD_DATA

constant Protocols.WebSocket.CLOSE_BAD_DATA


ConstantCLOSE_BAD_TYPE

constant Protocols.WebSocket.CLOSE_BAD_TYPE


ConstantCLOSE_ERROR

constant Protocols.WebSocket.CLOSE_ERROR


ConstantCLOSE_EXTENSION

constant Protocols.WebSocket.CLOSE_EXTENSION


ConstantCLOSE_GONE_AWAY

constant Protocols.WebSocket.CLOSE_GONE_AWAY


ConstantCLOSE_NONE

constant Protocols.WebSocket.CLOSE_NONE


ConstantCLOSE_NORMAL

constant Protocols.WebSocket.CLOSE_NORMAL


ConstantCLOSE_POLICY

constant Protocols.WebSocket.CLOSE_POLICY


ConstantCLOSE_UNEXPECTED

constant Protocols.WebSocket.CLOSE_UNEXPECTED

Enum Protocols.WebSocket.FRAME

Description

WebSocket frame opcodes.


ConstantFRAME_BINARY

constant Protocols.WebSocket.FRAME_BINARY


ConstantFRAME_CLOSE

constant Protocols.WebSocket.FRAME_CLOSE


ConstantFRAME_CONTINUATION

constant Protocols.WebSocket.FRAME_CONTINUATION


ConstantFRAME_PING

constant Protocols.WebSocket.FRAME_PING


ConstantFRAME_PONG

constant Protocols.WebSocket.FRAME_PONG


ConstantFRAME_TEXT

constant Protocols.WebSocket.FRAME_TEXT

Class Protocols.WebSocket.Connection


Variablebuf

Stdio.Buffer Protocols.WebSocket.Connection.buf

Description

Output buffer


VariablebufferedAmount

int Protocols.WebSocket.Connection.bufferedAmount

Description

Number of bytes in the send buffer.


Methodclose

voidclose(void|CLOSE_STATUSreason)

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.


Methodconnect

intconnect(Standards.URIendpoint, 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.


Methodcreate

Protocols.WebSocket.ConnectionProtocols.WebSocket.Connection()

Description

Create a WebSocket client


Methodcreate

Protocols.WebSocket.ConnectionProtocols.WebSocket.Connection(Stdio.File|SSL.Filef)

Description

Create a WebSocket server out of the given Stdio.File-like object


Variableendpoint

Standards.URI Protocols.WebSocket.Connection.endpoint

Description

Remote endpoint in client mode


Variablehttp_buffer

protectedStdio.Buffer Protocols.WebSocket.Connection.http_buffer

Description

Used in client mode to read server response.


Methodhttp_read

protectedvoidhttp_read(mixedid, stringdata)

Description

Read callback for HTTP answer when we are in client mode and have requested an upgrade to WebSocket.


Variablemasking

bool Protocols.WebSocket.Connection.masking

Description

If true, all outgoing frames are masked.


Variableonclose

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.


Variableonmessage

function(Frame, mixed:void) Protocols.WebSocket.Connection.onmessage


Variableonopen

function(mixed:void) Protocols.WebSocket.Connection.onopen


Variableparser

Parser Protocols.WebSocket.Connection.parser

Description

An instance of Parser used to parse incoming data.


Methodping

voidping(void|strings)

Description

Send a WebSocket ping frame.


Methodrequest_upgrade

protectedvoidrequest_upgrade()

Description

Write callback during the upgrade of a socket.


Methodsend

voidsend(Frameframe)

Description

Send a WebSocket frame.


Methodsend_binary

voidsend_binary(string(8bit)s)

Description

Send a WebSocket binary frame.


Methodsend_text

voidsend_text(strings)

Description

Send a WebSocket text frame.


Methodset_id

voidset_id(mixedid)

Description

Set the id. It will be passed as last argument to all callbacks.


Variablestate

STATE Protocols.WebSocket.Connection.state


Variablestream

Stdio.File|SSL.File Protocols.WebSocket.Connection.stream

Description

The actual client connection.

Enum Protocols.WebSocket.Connection.STATE


ConstantCLOSED

constant Protocols.WebSocket.Connection.CLOSED


ConstantCLOSING

constant Protocols.WebSocket.Connection.CLOSING


ConstantCONNECTING

constant Protocols.WebSocket.Connection.CONNECTING


ConstantOPEN

constant Protocols.WebSocket.Connection.OPEN

Class Protocols.WebSocket.Frame


Methodcreate

Protocols.WebSocket.FrameProtocols.WebSocket.Frame(FRAMEopcode, void|string|CLOSE_STATUS)
Protocols.WebSocket.FrameProtocols.WebSocket.Frame(FRAME_TEXT, stringtext)
Protocols.WebSocket.FrameProtocols.WebSocket.Frame(FRAME_BINARY, string(8bit)data)
Protocols.WebSocket.FrameProtocols.WebSocket.Frame(FRAME_CLOSE, CLOSE_STATUSreason)
Protocols.WebSocket.FrameProtocols.WebSocket.Frame(FRAME_PING, string(8bit)data)
Protocols.WebSocket.FrameProtocols.WebSocket.Frame(FRAME_PONG, string(8bit)data)


Variabledata

string Protocols.WebSocket.Frame.data

Description

Data part of the frame. Valid for frames of type FRAME_BINARY, FRAME_PING and FRAME_PONG.


Methodencode

voidencode(Stdio.Bufferbuf)


Variablefin

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.


Variableopcode

FRAME Protocols.WebSocket.Frame.opcode


Variablereason

CLOSE_STATUS Protocols.WebSocket.Frame.reason

Description

Only exists for frames of type FRAME_CLOSE.


Variabletext

string Protocols.WebSocket.Frame.text

Description

Only exists for frames of type FRAME_TEXT.

Class Protocols.WebSocket.Parser

Description

Parses WebSocket frames.


Variablebuf

Stdio.Buffer Protocols.WebSocket.Parser.buf

Description

Unparsed data.


Methodfeed

voidfeed(stringdata)

Description

Add more data to the internal parsing buffer.


Methodparse

Frameparse()

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


InheritPort

inherit Protocols.HTTP.Server.Port : Port

Class Protocols.WebSocket.Request


Variablecb

function(array(string), Request:void) Protocols.WebSocket.Request.cb


Methodcreate

Protocols.WebSocket.RequestProtocols.WebSocket.Request(function(array(string), Request:void) cb)


InheritRequest

inherit Protocols.HTTP.Server.Request : Request


Methodwebsocket_accept

Connectionwebsocket_accept(stringprotocol)

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


InheritSSLPort

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


MethodInternAtom

objectInternAtom(stringname, function(:void)|voidcallback)

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.


Methodinit

intinit(objectd)

Description

initialize the extension.

Parameter d

An object of type Protocols.X.Xlib.Display

Class Protocols.X.Extensions.ScreenSaver


InheritExtension

inherit Extension : Extension

Class Protocols.X.Extensions.Shape


MethodShapeMask

voidShapeMask(objectwindow, intxo, intyo, stringkind, stringoperation, object|voidsource)


MethodShapeOffset

voidShapeOffset(objectwindow, stringkind, intxo, intyo)


MethodShapeRectangles

voidShapeRectangles(objectwindow, intxo, intyo, stringkind, stringoperation, .Types.Rectangle|array(.Types.Rectangle) rectangles)


InheritExtension

inherit Extension : Extension

Class Protocols.X.Extensions.XTEST

Description

Provides support for the X11 XTEST extension.


MethodXTestFakeInput

voidXTestFakeInput(stringevent_type, intdetail, intdelay, object|voidwindow, int|voidxloc, int|voidyloc)

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.


MethodXTestGrabControl

voidXTestGrabControl(intimpervious)

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.


Methodcreate

Protocols.X.Extensions.XTESTProtocols.X.Extensions.XTEST()

Description

Create object.


InheritExtension

inherit Extension : Extension


Methodinit

intinit(objectdisplay)

Description

Initialize the XTEST extension. Returns 1 if successful.

Parameter display

Protocols.X.Display object

Module Protocols.X.KeySyms


MethodLookupCharacter

intLookupCharacter(stringstr)


MethodLookupKeycode

intLookupKeycode(intkeysym, objectdisplay)


MethodLookupKeysym

stringLookupKeysym(intkeysym, objectdisplay)


MethodReleaseKey

voidReleaseKey(intsym)


Method_LookupCharacter

int_LookupCharacter(stringstr)


Method_LookupKeysym

string_LookupKeysym(intkeysym)


Variablealt_gr
Variablenum_lock
Variableshift
Variablecontrol
Variablecaps_lock
Variablemeta
Variablealt
Variablesuper
Variablehyper

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


Variableattributes

mapping Protocols.X.KeySyms.attributes


MethodmakeKeysymtoKeycode

voidmakeKeysymtoKeycode(objectdisplay)


Variablestringtokeysyms

mapping Protocols.X.KeySyms.stringtokeysyms

Module Protocols.X.Requests

Description

Varios X11 on-wire requests

Class Protocols.X.Requests.AllocColor


Variablered
Variablegreen
Variableblue
Variablecolormap

int Protocols.X.Requests.AllocColor.red
int Protocols.X.Requests.AllocColor.green
int Protocols.X.Requests.AllocColor.blue
int Protocols.X.Requests.AllocColor.colormap


Inheritrequest

inherit request : request

Class Protocols.X.Requests.Bell


Inheritrequest

inherit request : request


Variablepercent

int Protocols.X.Requests.Bell.percent

Class Protocols.X.Requests.ChangeGC


Variablegc
Variableattributes

int Protocols.X.Requests.ChangeGC.gc
mapping Protocols.X.Requests.ChangeGC.attributes


Inheritrequest

inherit request : request

Class Protocols.X.Requests.ChangeProperty


Variablemode
Variablewindow
Variableproperty
Variabletype
Variableformat
Variabledata

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.ChangeWindowAttributes


Variablewindow
Variableattributes

int Protocols.X.Requests.ChangeWindowAttributes.window
mapping Protocols.X.Requests.ChangeWindowAttributes.attributes


Inheritrequest

inherit request : request

Class Protocols.X.Requests.ClearArea


Variableexposures
Variablewindow
Variablex
Variabley
Variablewidth
Variableheight

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.CloseFont


InheritFreeRequest

inherit FreeRequest : FreeRequest

Class Protocols.X.Requests.ConfigureWindow


Variableattributes

mapping Protocols.X.Requests.ConfigureWindow.attributes


Inheritrequest

inherit request : request

Class Protocols.X.Requests.CopyArea


Variablegc
Variablearea
Variablesrc
Variabledst
Variablex
Variabley

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.CopyPlane


InheritCopyArea

inherit CopyArea : CopyArea


Variableplane

int Protocols.X.Requests.CopyPlane.plane

Class Protocols.X.Requests.CreateColormap


Variablecid
Variablealloc

int Protocols.X.Requests.CreateColormap.cid
int Protocols.X.Requests.CreateColormap.alloc


Inheritrequest

inherit request : request


Variablewindow
Variablevisual

int Protocols.X.Requests.CreateColormap.window
int Protocols.X.Requests.CreateColormap.visual

Class Protocols.X.Requests.CreateGC


Variablegc
Variabledrawable
Variableattributes

int Protocols.X.Requests.CreateGC.gc
int Protocols.X.Requests.CreateGC.drawable
mapping Protocols.X.Requests.CreateGC.attributes


Inheritrequest

inherit request : request

Class Protocols.X.Requests.CreateGlyphCursor


Variablecid
Variablesourcefont
Variablemaskfont
Variablesourcechar
Variablemaskchar
Variableforered
Variableforegreen
Variableforeblue
Variablebackred
Variablebackgreen
Variablebackblue

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.CreatePixmap


Variabledepth

int Protocols.X.Requests.CreatePixmap.depth


Variablepid
Variabledrawable

int Protocols.X.Requests.CreatePixmap.pid
int Protocols.X.Requests.CreatePixmap.drawable


Variablewidth
Variableheight

int Protocols.X.Requests.CreatePixmap.width
int Protocols.X.Requests.CreatePixmap.height


Inheritrequest

inherit request : request

Class Protocols.X.Requests.CreateWindow


Variableattributes

mapping Protocols.X.Requests.CreateWindow.attributes


Variablex
Variabley
Variablewidth
Variableheight
VariableborderWidth

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


Variablec_class
Variablevisual

int Protocols.X.Requests.CreateWindow.c_class
int Protocols.X.Requests.CreateWindow.visual


Variabledepth

int Protocols.X.Requests.CreateWindow.depth


Inheritrequest

inherit request : request


Variablewid
Variableparent

int Protocols.X.Requests.CreateWindow.wid
int Protocols.X.Requests.CreateWindow.parent

Class Protocols.X.Requests.DeleteProperty


Inheritrequest

inherit request : request


Variablewindow
Variableproperty

int Protocols.X.Requests.DeleteProperty.window
int Protocols.X.Requests.DeleteProperty.property

Class Protocols.X.Requests.ExtensionRequest

Description

Base class used by extensions


Variabletype
Variablecode
Variabledata
Variablehandle_reply
Variablehandle_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


Variabledrawable
Variablegc
Variableshape
VariablecoordMode

int Protocols.X.Requests.FillPoly.drawable
int Protocols.X.Requests.FillPoly.gc
int Protocols.X.Requests.FillPoly.shape
int Protocols.X.Requests.FillPoly.coordMode


Inheritrequest

inherit request : request


Variablepoints

array Protocols.X.Requests.FillPoly.points

Class Protocols.X.Requests.FreeColormap


InheritFreeRequest

inherit FreeRequest : FreeRequest

Class Protocols.X.Requests.FreeColors


Variablecolors
Variablecolormap
Variableplane_mask

array Protocols.X.Requests.FreeColors.colors
int Protocols.X.Requests.FreeColors.colormap
int Protocols.X.Requests.FreeColors.plane_mask


Inheritrequest

inherit request : request

Class Protocols.X.Requests.FreeCursor


InheritFreeRequest

inherit FreeRequest : FreeRequest

Class Protocols.X.Requests.FreeGC


InheritFreeRequest

inherit FreeRequest : FreeRequest

Class Protocols.X.Requests.FreePixmap


InheritFreeRequest

inherit FreeRequest : FreeRequest

Class Protocols.X.Requests.FreeRequest


Variableid

int Protocols.X.Requests.FreeRequest.id


Inheritrequest

inherit request : request

Class Protocols.X.Requests.GetAtomName


Variableatom

int Protocols.X.Requests.GetAtomName.atom


Inheritrequest

inherit request : request

Class Protocols.X.Requests.GetKeyboardMapping


Variablefirst
Variablenum

int Protocols.X.Requests.GetKeyboardMapping.first
int Protocols.X.Requests.GetKeyboardMapping.num


Inheritrequest

inherit request : request

Class Protocols.X.Requests.GetProperty


Variabledelete
Variablewindow
Variableproperty
Variabletype
VariablelongOffset
VariablelongLength

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.GrabButton


VariableownerEvents
VariablegrabWindow
VariableeventMask
VariablepointerMode
VariablekeyboardMode
VariableconfineTo
Variablecursor
Variablebutton
Variablemodifiers

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.ImageText16


Variabledrawable
Variablegc
Variablex
Variabley
Variablestr

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.ImageText8


Variabledrawable
Variablegc
Variablex
Variabley
Variablestr

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.InternAtom


Inheritrequest

inherit request : request


VariableonlyIfExists
Variablename

int Protocols.X.Requests.InternAtom.onlyIfExists
string Protocols.X.Requests.InternAtom.name

Class Protocols.X.Requests.ListProperties


Inheritrequest

inherit request : request


Variablewindow

int Protocols.X.Requests.ListProperties.window

Class Protocols.X.Requests.MapWindow


InheritResourceReq

inherit ResourceReq : ResourceReq

Class Protocols.X.Requests.OpenFont


Variablefid
Variablename

int Protocols.X.Requests.OpenFont.fid
string Protocols.X.Requests.OpenFont.name


Inheritrequest

inherit request : request

Class Protocols.X.Requests.PolyFillRectangle


Variabledrawable
Variablegc

int Protocols.X.Requests.PolyFillRectangle.drawable
int Protocols.X.Requests.PolyFillRectangle.gc


Inheritrequest

inherit request : request


Variablerectangles

array Protocols.X.Requests.PolyFillRectangle.rectangles

Class Protocols.X.Requests.PolyLine


InheritPolyPoint

inherit PolyPoint : PolyPoint

Class Protocols.X.Requests.PolyPoint


VariablecoordMode
Variabledrawable
Variablegc
Variablepoints

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


Inheritrequest

inherit request : request

Class Protocols.X.Requests.PutImage


Variabledata

string Protocols.X.Requests.PutImage.data


Variabledepth
Variablewidth
Variableheight
Variabledst_x
Variabledst_y
Variableleft_pad
Variableformat

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


Variabledrawable
Variablegc

int Protocols.X.Requests.PutImage.drawable
int Protocols.X.Requests.PutImage.gc


Inheritrequest

inherit request : request

Class Protocols.X.Requests.QueryExtension


Inheritrequest

inherit request : request


Variablename

string Protocols.X.Requests.QueryExtension.name

Class Protocols.X.Requests.QueryTextExtents


Variablefont
Variablestr

int Protocols.X.Requests.QueryTextExtents.font
string Protocols.X.Requests.QueryTextExtents.str


Inheritrequest

inherit request : request

Class Protocols.X.Requests.ResourceReq


Inheritrequest

inherit request : request

Class Protocols.X.Requests.UnmapWindow


InheritResourceReq

inherit ResourceReq : ResourceReq

Module Protocols.X.Types

Class Protocols.X.Types.Colormap


MethodAllocColor

intAllocColor(intr, intg, intb)


MethodFreeColor

voidFreeColor(intpixel)


Variablevisual
Variablealloced

object Protocols.X.Types.Colormap.visual
mapping Protocols.X.Types.Colormap.alloced


InheritXResource

inherit XResource : XResource

Class Protocols.X.Types.Cursor


InheritXResource

inherit XResource : XResource

Class Protocols.X.Types.Drawable


MethodCopyArea

objectCopyArea(objectgc, objectsrc, objectarea, intx, inty)


MethodCopyArea_req

objectCopyArea_req(objectgc, objectsrc, objectarea, intx, inty)


MethodCreateGC

objectCreateGC(mapping|voidattributes)


MethodCreateGC_req

objectCreateGC_req()


MethodCreatePixmap

objectCreatePixmap(intwidth, intheight, intdepth)


MethodCreatePixmap_req

objectCreatePixmap_req(intwidth, intheight, intdepth)


MethodDrawLine

voidDrawLine(objectgc, intcoordMode, object ... points)


MethodDrawLine_req

objectDrawLine_req(intgc, intcoordMode, array(object) points)


MethodFillPoly

voidFillPoly(objectgc, intshape, intcoordMode, array(object) points)


MethodFillPoly_req

objectFillPoly_req(intgc, intshape, intcoordMode, array(object) p)


MethodFillRectangles

voidFillRectangles(objectgc, object ... r)


MethodFillRectangles_req

objectFillRectangles_req(intgc, array(object) r)


MethodImageText16

voidImageText16(objectgc, intx, inty, stringstr)


MethodImageText16_req

objectImageText16_req(intgc, intx, inty, stringstr)


MethodImageText8

voidImageText8(objectgc, intx, inty, stringstr)


MethodImageText8_req

objectImageText8_req(intgc, intx, inty, stringstr)


MethodPutImage

voidPutImage(objectgc, intdepth, inttx, intty, intwidth, intheight, stringdata, int|voidformat)


MethodPutImage_req

objectPutImage_req(objectgc, intdepth, inttx, intty, intwidth, intheight, stringdata)


InheritXResource

inherit XResource : XResource

Class Protocols.X.Types.Font


MethodCreateGlyphCursor

objectCreateGlyphCursor(intsourcechar, array(int)|voidforeground, array(int)|voidbackground)


MethodQueryTextExtents

mapping(string:int) QueryTextExtents(stringstr)


MethodQueryTextExtents16

mapping(string:int) QueryTextExtents16(stringstr)


MethodQueryTextExtents_req

objectQueryTextExtents_req(stringstr)


InheritXResource

inherit XResource : XResource

Class Protocols.X.Types.GC


MethodChangeGC

voidChangeGC(mappingattributes)


MethodChangeGC_req

objectChangeGC_req(mappingattributes)


MethodGetGCValues

mapping(string:mixed) GetGCValues()


InheritXResource

inherit XResource : XResource


Variablevalues

mapping(string:mixed) Protocols.X.Types.GC.values

Class Protocols.X.Types.Pixmap


InheritDrawable

inherit Drawable : Drawable

Class Protocols.X.Types.Point


Variablex
Variabley

int Protocols.X.Types.Point.x
int Protocols.X.Types.Point.y

Class Protocols.X.Types.Rectangle


Variablewidth
Variableheight

int Protocols.X.Types.Rectangle.width
int Protocols.X.Types.Rectangle.height


Variablex
Variabley

int Protocols.X.Types.Rectangle.x
int Protocols.X.Types.Rectangle.y

Class Protocols.X.Types.RootWindow


VariabledefaultColorMap
VariablewhitePixel
VariableblackPixel
VariablepixWidth
VariablepixHeight
VariablemmWidth
VariablemmHeight
VariableminInstalledMaps
VariablemaxInstalledMaps
VariablebackingStore
VariablesaveUnders
VariablerootDepth
Variabledepths

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


InheritWindow

inherit Window : Window

Class Protocols.X.Types.Visual


Variablec_class
VariablebitsPerRGB
VariablecolorMapEntries
VariableredMask
VariablegreenMask
VariableblueMask

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


Variabledepth

int Protocols.X.Types.Visual.depth


InheritXResource

inherit XResource : XResource

Class Protocols.X.Types.Window


MethodChangeAttributes

voidChangeAttributes(mappingm)


MethodChangeAttributes_req

objectChangeAttributes_req(mappingm)


MethodChangeProperty

voidChangeProperty(objectproperty, objecttype, intformat, array(int)|stringdata)


MethodChangeProperty_req

objectChangeProperty_req(objectproperty, objecttype, intformat, array(int)|stringdata)


MethodClearArea

voidClearArea(intx, inty, intwidth, intheight, int|voidexposures)


MethodClearArea_req

objectClearArea_req(intx, inty, intwidth, intheight, intexposures)


MethodConfigure

voidConfigure(mappingm)


MethodConfigure_req

objectConfigure_req(mappingm)


MethodCreateColormap

objectCreateColormap(objectvisual, int|voidalloc)


MethodCreateSimpleWindow

objectCreateSimpleWindow(intx, inty, intwidth, intheight, intborder_width, intborder, intbackground)


MethodCreateWindow

objectCreateWindow(intx, inty, intwidth, intheight, intborder_width, mapping|voidattributes, object|voidvisual, int|voidd, int|voidc_class)


MethodCreateWindow_req

objectCreateWindow_req(intx, inty, intwidth, intheight, intborder_width, intdepth, objectvisual)


MethodDeselectInput

intDeselectInput(string ... types)


MethodGetProperty

mappingGetProperty(objectproperty, object|voidtype)


MethodGetProperty_req

objectGetProperty_req(objectproperty, object|voidtype)


MethodGrabButton

voidGrabButton(intbutton, intmodifiers, string ... types)


MethodGrabButton_req

objectGrabButton_req(intbutton, intmodifiers, array(string) types)


MethodListProperties

arrayListProperties()


MethodListProperties_req

objectListProperties_req()


MethodLower

voidLower()


MethodMap

voidMap()


MethodMap_req

objectMap_req()


MethodRaise

voidRaise()


MethodSelectInput

intSelectInput(string ... types)


MethodSelectInput_req

objectSelectInput_req()


MethodShapeMask

voidShapeMask(stringkind, intxo, intyo, stringoperation, Pixmapmask)


MethodShapeOffset

voidShapeOffset(stringkind, intxo, intyo)


MethodShapeRectangles

voidShapeRectangles(stringkind, intxo, intyo, stringoperation, array(Rectangle) rectangles)


MethodUnmap

voidUnmap()


MethodUnmap_req

objectUnmap_req()


VariablecurrentInputMask

int Protocols.X.Types.Window.currentInputMask


Variableevent_callbacks

mapping(string:array(array)) Protocols.X.Types.Window.event_callbacks


InheritDrawable

inherit Drawable : Drawable


InheritKeySyms

inherit .KeySyms : KeySyms


Methodset_event_callback

voidset_event_callback(stringtype, function(:void) f, int|voidpriority)

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


MethodFree

voidFree()


Variabledisplay
Variableid
Variableautofree

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.


MethodMakeShapeMask

objectMakeShapeMask(objectin, objectalpha)

Description

Convert an alpha channel to a shaped-window extension mask


MethodShapedWindowImage

voidShapedWindowImage(objectin, objectcolor, object|voidalpha, int|voidcontour)

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)


InheritXImage

inherit XImage : XImage

Class Protocols.X.XImage.WindowImage

Description

A version of XImage that redraws itself at need


InheritXImage

inherit XImage : XImage

Class Protocols.X.XImage.XImage


Methodallocate_colortable

Image.Colortableallocate_colortable()


Variablebest

int Protocols.X.XImage.XImage.best


Variabledepth
Variablebpp
Variableconverter
Variablelinepad
Variableswapbytes
Variablermask
Variablegmask
Variablebmask

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


Variablewindow
Variableroot
Variablevisual
Variablecolormap
Variableccol
Variabledgc

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


InheritImage_wrapper

inherit Image_wrapper : Image_wrapper


Variableoffset_x
Variableoffset_y

int Protocols.X.XImage.XImage.offset_x
int Protocols.X.XImage.XImage.offset_y


Methodredraw

voidredraw(intx, inty, intwidth, intheight)


Methodset_drawable

voidset_drawable(objectw)


Methodset_offset

voidset_offset(intx, inty)


Methodset_window

voidset_window(objectw)

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


Variablepressed
Variableinside
Variablebutton

int Protocols.X.XTools.Button.pressed
int Protocols.X.XTools.Button.inside
int Protocols.X.XTools.Button.button


Methodbutton_exposed

voidbutton_exposed(mappingevent)


Methodbutton_pressed

mappingbutton_pressed(mappingevent)


Methodbutton_released

mappingbutton_released(mappingevent)


Methodcreate

Protocols.X.XTools.ButtonProtocols.X.XTools.Button(objectw, int|voidb)


Methodwindow_entered

mappingwindow_entered(mappingevent)


Methodwindow_left

mappingwindow_left(mappingevent)

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.


MethodBell

voidBell(intvolume)


MethodBell_req

objectBell_req(intvolume)


MethodCreateGlyphCursor

objectCreateGlyphCursor(objectsourcefont, intsourcechar, object|voidmaskfont, int|voidmaskchar, array(int)|voidforeground, array(int)|voidbackground)


MethodCreateGlyphCursor_req

objectCreateGlyphCursor_req(objectsourcefont, objectmaskfont, intsourcechar, intmaskchar, array(int) foreground, array(int) background)


MethodDefaultRootWindow

objectDefaultRootWindow()


MethodOpenFont

objectOpenFont(stringname)


MethodOpenFont_req

objectOpenFont_req(stringname)


VariableimageByteOrder
VariablebitmapBitOrder

int Protocols.X.Xlib.Display.imageByteOrder
int Protocols.X.Xlib.Display.bitmapBitOrder


VariablebitmapScanlineUnit
VariablebitmapScanlinePad

int Protocols.X.Xlib.Display.bitmapScanlineUnit
int Protocols.X.Xlib.Display.bitmapScanlinePad


Methodblocking_request

arrayblocking_request(.Requests.requestreq)


Variableextensions

mapping(string:.Extensions.Extension) Protocols.X.Xlib.Display.extensions

Description

All extensions supported by the server and this module


Variableformats

array Protocols.X.Xlib.Display.formats


InheritFile

inherit Stdio.File : File


Inheritatom_manager

inherit .Atom.atom_manager : atom_manager


Inheritid_manager

inherit id_manager : id_manager


Variablekey_mapping

array Protocols.X.Xlib.Display.key_mapping


VariablemajorVersion
VariableminorVersion

int Protocols.X.Xlib.Display.majorVersion
int Protocols.X.Xlib.Display.minorVersion

Description

The protocol major and minor version reported by the server


VariableminKeyCode
VariablemaxKeyCode

int Protocols.X.Xlib.Display.minKeyCode
int Protocols.X.Xlib.Display.maxKeyCode


VariablemaxRequestSize

int Protocols.X.Xlib.Display.maxRequestSize


VariablemotionBufferSize

int Protocols.X.Xlib.Display.motionBufferSize


Methodopen

intopen(string|voiddisplay)

Description

Connect to the specified display. The default is to use the value of the environment variable DISPLAY


Variablerelease

int Protocols.X.Xlib.Display.release

Description

Server release number


Variableroots

array Protocols.X.Xlib.Display.roots


Variablescreen_number

int Protocols.X.Xlib.Display.screen_number


Methodsend_async_request

voidsend_async_request(.Requests.requestreq, function(:void) callback)


Variablevendor

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.


Methoddecode_call

Calldecode_call(stringxml_input)

Description

Decodes a XML-RPC representation of a function call and returns a Call object.

See also

Call


Methoddecode_response

array|Faultdecode_response(stringxml_input, int|voidboolean)

Description

Decodes a XML-RPC representation of a response and returns an array containing response values, or a Fault object.

See also

Fault


Methodencode_call

stringencode_call(stringmethod_name, arrayparams)

Description

Encodes a function call with the name method_name and the arguments params and returns the XML-RPC string representation.


Methodencode_response

stringencode_response(arrayparams)

Description

Encodes a response containing the multiple values in params and returns the XML-RPC string representation.


Methodencode_response_fault

stringencode_response_fault(intfault_code, stringfault_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()


Methodcreate

Protocols.XMLRPC.CallProtocols.XMLRPC.Call(stringmethod_name, arrayparams)


Variablemethod_name

int Protocols.XMLRPC.Call.method_name

Description

Represents <methodName> in the XML-RPC standard.


Variablemethod_name
Variableparams

string Protocols.XMLRPC.Call.method_name
array Protocols.XMLRPC.Call.params


Variableparams

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"
  		    })
  		})
 

Variableurl
Variableboolean

string|Standards.URI Protocols.XMLRPC.Client.url
int|void Protocols.XMLRPC.Client.boolean


Methodcreate

Protocols.XMLRPC.ClientProtocols.XMLRPC.Client(string|Standards.URIurl, int|voidboolean)

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


Methodcreate

Protocols.XMLRPC.FaultProtocols.XMLRPC.Fault(intfault_code, stringfault_string)


Variablefault_code
Variablefault_string

int Protocols.XMLRPC.Fault.fault_code
string Protocols.XMLRPC.Fault.fault_string


Variablefault_code

int Protocols.XMLRPC.Fault.fault_code

Description

Represents faultCode in the XML-RPC standard.


Variablefault_string

int Protocols.XMLRPC.Fault.fault_string

Description

Represents faultString in the XML-RPC standard.

Class Protocols.XMLRPC.StringWrap


Methodcreate

Protocols.XMLRPC.StringWrapProtocols.XMLRPC.StringWrap(strings)


Variables

string Protocols.XMLRPC.StringWrap.s