| 13. Protocols |
| Module Protocols.HTTP |
.Query do_method(string method, string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con, void|string data)
Low level HTTP call method.
The HTTP method to use, e.g. "GET".
The URL to perform method on. Should be a complete URL,
including protocol, e.g. "https://pike.ida.liu.se/".
Calls http_encode_query and appends the result to the URL.
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.
Old connection object.
Data payload to be transmitted in the request.
do_sync_method()
void do_async_method(string method, string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, Protocols.HTTP.Query con, void|string data)
Low level asynchronous HTTP call method.
The HTTP method to use, e.g. "GET".
The URL to perform method on. Should be a complete URL,
including protocol, e.g. "https://pike.ida.liu.se/".
Calls http_encode_query and appends the result to the URL.
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.
Previously initialized connection object. In particular the callbacks must have been set (Query.set_callbacks() ).
Data payload to be transmitted in the request.
do_method() , Query.set_callbacks()
.Query get_url(string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
.Query put_url(string|Standards.URI url, void|string file, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
.Query delete_url(string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
array(string) get_url_nice(string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
string get_url_data(string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
.Query post_url(string|Standards.URI url, mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
Similar to get_url , except that query variables is sent as a POST request instead of a GET request.
array(string) post_url_nice(string|Standards.URI url, mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
Similar to get_url_nice , except that query variables is sent as a POST request instead of a GET request.
string post_url_data(string|Standards.URI url, mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
Similar to get_url_data , except that query variables is sent as a POST request instead of a GET request.
string http_encode_query(mapping(string:int|string|array(string)) variables)
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"
string percent_encode(string s)
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.
string percent_decode(string s)
Decodes URI-style %XX encoded chars in the given string.
percent_encode , uri_decode
This function currently does not accept wide string input, which is necessary to work as the reverse of iri_encode .
string uri_encode(string s)
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.
uri_decode , uri_encode_invalids , iri_encode
string uri_encode_invalids(string s)
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.
The characters in the URI reserved set are: :, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ;, =. In addition, this function doesn't touch the escape char %.
uri_decode , uri_encode
string uri_decode(string s)
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 .
uri_encode , uri_encode_invalids
string iri_encode(string s)
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.
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.
percent_decode , uri_encode
string uri_normalize(string s)
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.
uri_decode , uri_encode , iri_normalize
string iri_normalize(string s)
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.
iri_decode , uri_normalize
string quoted_string_encode(string s)
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.
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.
quoted_string_decode
string quoted_string_decode(string s)
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.
quoted_string_encode
__deprecated__ string http_encode_string(string in)
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__ string http_encode_cookie(string f)
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__ string unentity(string s)
Helper function for replacing HTML entities with the corresponding unicode characters.
| CLASS Protocols.HTTP.Query |
Open and execute an HTTP query.
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.ida.liu.se", 80, "HEAD / HTTP/1.0"); return -1; }
int Protocols.HTTP.Query.errno
Errno copied from the connection.
int Protocols.HTTP.Query.ok
Tells if the connection is successfull.
mapping Protocols.HTTP.Query.headers
Headers as a mapping. All header names are in lower case, for convinience.
string Protocols.HTTP.Query.protocol
Protocol string, ie "HTTP/1.0".
int Protocols.HTTP.Query.status
string Protocols.HTTP.Query.status_desc
Status number and description (eg 200 and "ok").
mapping Protocols.HTTP.Query.hostname_cache
Set this to a global mapping if you want to use a cache, prior of calling *request().
Protocols.HTTP.Query set_callbacks(function request_ok, function request_fail, mixed ... extra)
Protocols.HTTP.Query async_request(string server, int port, string query)
Protocols.HTTP.Query async_request(string server, int port, string query, mapping headers, string|void data)
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 the called object
Protocols.HTTP.Query thread_request(string server, int port, string query)
Protocols.HTTP.Query thread_request(string server, int port, string query, mapping headers, void|string data)
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 the called object.
int `()()
Wait for connection to complete.
Returns 1 on successfull connection, 0 on failure.
string data(int|void max_length)
Gives back the data as a string.
string unicode_data()
Gives back data, but decoded according to the content-type character set.
data
int downloaded_bytes()
Gives back the number of downloaded bytes.
int total_bytes()
Gives back the size of a file if a content-length header is present and parsed at the time of evaluation. Otherwise returns -1.
array cast("array")
| ||||||||||||
mapping cast("mapping")
The header mapping ORed with the following mapping.
|
string cast("string")
Gives back the answer as a string.
Protocols.HTTP.Query.PseudoFile file()
Protocols.HTTP.Query.PseudoFile file(mapping newheaders, void|mapping removeheaders)
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.
datafile()
Protocols.HTTP.Query.PseudoFile datafile()
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.
file()
void async_fetch(function callback, mixed ... extra)
Fetch all data in background.
timed_async_fetch() , async_request() , set_callbacks()
void timed_async_fetch(function(object:void) ok_callback, function(object:void) fail_callback, mixed ... extra)
Like async_fetch() , except with a timeout and a corresponding fail callback function.
async_fetch() , async_request() , set_callbacks()
| CLASS Protocols.HTTP.Session |
int Protocols.HTTP.Session.follow_redirects
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.
Loops will currently not be detected, only the limit works to stop loops.
Request.follow_redirects
mapping Protocols.HTTP.Session.default_headers
Default HTTP headers.
void set_http_cookie(string cookie, Standards.URI at)
Parse and set a cookie received in the HTTP protocol. The cookie will be checked against current security levels et al.
void set_cookie(Cookie cookie, Standards.URI who)
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.
string encode_cookies()
void decode_cookies(string data, void no_clear)
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.
array(string) get_cookies(Standards.URI|SessionURL for_url, void|int(0..1) no_delete)
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.
mapping Protocols.HTTP.Session.hostname_cache
Cache of hostname to IP lookups. Given to and used by the Query objects.
int|float Protocols.HTTP.Session.time_to_keep_unused_connections
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.
int Protocols.HTTP.Session.maximum_connections_per_server
Maximum number of connections to the same server. Used only by async requests. Defaults to 10 connections.
int Protocols.HTTP.Session.maximum_total_connections
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.
int Protocols.HTTP.Session.maximum_connection_reuse
Maximum times a connection is reused. Defaults to 1000000. <2 means no reuse at all.
Query give_me_connection(Standards.URI url)
Request a Query object suitable to use for the given URL. This may be a reused object from a keep-alive connection.
void return_connection(Standards.URI url, Query query)
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.
Request get_url(URL url, void|mapping query_variables)
Request post_url(URL url, mapping query_variables)
Request put_url(URL url, string file, void|mapping query_variables)
Request delete_url(URL url, void|mapping query_variables)
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.
array(string) get_url_nice(URL url, mapping query_variables)
string get_url_data(URL url, mapping query_variables)
array(string) post_url_nice(URL url, mapping query_variables)
string post_url_data(URL url, mapping query_variables)
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.
Request async_get_url(URL url, void|mapping query_variables, function callback_headers_ok, function callback_data_ok, function callback_fail, mixed ... callback_arguments)
Request async_put_url(URL url, void|string file, void|mapping query_variables, function callback_headers_ok, function callback_data_ok, function callback_fail, mixed ... callback_arguments)
Request async_delete_url(URL url, void|mapping query_variables, function callback_headers_ok, function callback_data_ok, function callback_fail, mixed ... callback_arguments)
Request async_post_url(URL url, mapping query_variables, function callback_headers_ok, function callback_data_ok, function callback_fail, mixed ... callback_arguments)
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.
| CLASS Protocols.HTTP.Session.Request |
Request
Query Protocols.HTTP.Session.Request.con
Raw connection object
Standards.URI Protocols.HTTP.Session.Request.url_requested
URL requested (set by prepare_method). This will update according to followed redirects.
int Protocols.HTTP.Session.Request.follow_redirects
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.
Loops will currently not be detected, only the limit works to stop loops.
function(string:mixed) Protocols.HTTP.Session.Request.cookie_encountered
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.
array(string|int|mapping) prepare_method(string method, URL url, void|mapping query_variables, void|mapping extra_headers, void|string data)
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).
Request do_sync(array(string|int|mapping) args)
Perform a request synchronously. Get arguments from prepare_method .
0 upon failure, this object upon success
prepare_method , do_async , do_thread
Request do_thread(array(string|int|mapping) args)
Start a request in the background, using a thread. Call wait to wait for the thread to finish. Get arguments from prepare_method .
The called object.
prepare_method , do_sync , do_async , wait
do_thread does not rerun redirections automatically
Request wait()
Wait for the request thread to finish.
0 upon failure, or the called object upon success.
do_thread
void set_callbacks(function(mixed ... :mixed) headers, function(mixed ... :mixed) data, function(mixed ... :mixed) fail, mixed ... callback_arguments)
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.
Request do_async(array(string|int|mapping) args)
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 .
The called object.
set_callbacks , prepare_method , do_sync , do_thread
void destroy()
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.
| CLASS Protocols.HTTP.Session.SessionURL |
Class to store URL+referer
inherit Standards.URI : URI
URL Protocols.HTTP.Session.SessionURL.referer
the referer to this URL
void Protocols.HTTP.Session.SessionURL(URL uri, URL base_uri, URL _referer)
instantiate a SessionURL object; when fed to Protocols.HTTP.Session calls, will add referer to the HTTP handshaking variables
| Module Protocols.HTTP.Server |
constant Protocols.HTTP.Server.HeaderParser
Fast HTTP header parser.
constant Protocols.HTTP.Server.http_decode_string
mapping(string:string|array(string)) http_decode_urlencoded_query(string query, void|mapping dest)
Decodes an URL-encoded query into a mapping.
string extension_to_type(string extension)
Looks up the file extension in a table to return a suitable MIME type.
string filename_to_type(string filename)
Looks up the file extension in a table to return a suitable MIME type.
string http_date(int time)
Makes a time notification suitable for the HTTP protocol.
The time in seconds since the 00:00:00 UTC, January 1, 1970
The date in the HTTP standard date format. Example : Thu, 03 Aug 2000 05:40:39 GMT
int http_decode_date(string data)
Decode a HTTP date to seconds since 1970 (UTC)
zero (UNDEFINED) if the given string isn't a HTTP date
| CLASS Protocols.HTTP.Server.Request |
string Protocols.HTTP.Server.Request.raw
raw unparsed full request (headers and body)
string Protocols.HTTP.Server.Request.body_raw
raw unparsed body of the request (raw minus request line and headers)
string Protocols.HTTP.Server.Request.request_raw
full request line (request_type + full_query + protocol )
string Protocols.HTTP.Server.Request.request_type
HTTP request method, eg. POST, GET, etc.
string Protocols.HTTP.Server.Request.full_query
full resource requested, including attached GET query
string Protocols.HTTP.Server.Request.not_query
resource requested minus any attached query
string Protocols.HTTP.Server.Request.query
query portion of requested resource, starting after the first "?"
string Protocols.HTTP.Server.Request.protocol
request protocol and version, eg. HTTP/1.0
mapping(string:string|array(string)) Protocols.HTTP.Server.Request.request_headers
all headers included as part of the HTTP request, ie content-type.
mapping(string:string|array(string)) Protocols.HTTP.Server.Request.variables
all variables included as part of a GET or POST request.
mapping(string:string) Protocols.HTTP.Server.Request.cookies
cookies set by client
mapping Protocols.HTTP.Server.Request.misc
external use only
int Protocols.HTTP.Server.Request.send_timeout_delay
send timeout (no activity for this period with data in send buffer) in seconds, default is 180
int Protocols.HTTP.Server.Request.connection_timeout_delay
connection timeout, delay until connection is closed while waiting for the correct headers:
void response_and_finish(mapping m, function|void _log_cb)
return a properly formatted response to the HTTP client
Contains elements for generating a response to the client.
|
int sent_data()
Returns the amount of data sent.
| CLASS Protocols.HTTP.Server.Port |
The simplest server possible. Binds a port and calls a callback with Server.Request objects.
void Protocols.HTTP.Server.Port(function(.Request:void) callback)
void Protocols.HTTP.Server.Port(function(.Request:void) callback, int portno, void|string interface)
void close()
Closes the HTTP port.
| CLASS Protocols.HTTP.Server.SSLPort |
The simplest SSL server possible. Binds a port and calls a callback with Request objects.
void Protocols.HTTP.Server.SSLPort(function(Request:void) _callback, void|int _portno, void|string _interface, void|string key, void|string|array certificate)
Create a HTTPS (HTTP over SSL) server.
The function run when a request is received. takes one argument of type Request .
The port number to bind to, defaults to 443.
The interface address to bind to.
An optional SSL secret key, provided in binary format, such as that created by Standards.PKCS.RSA.private_key() .
An optional SSL certificate or chain of certificates with the host certificate first, provided in binary format.
void close()
Closes the HTTP port.
void new_connection()
The port accept callback
| CLASS Protocols.HTTP.Server.SSLPort.MySSLPort |
inherit SSL.sslport : sslport
void set_default_keycert()
void set_key(string skey)
void set_certificate(string|array(string) certificate)
| Module SSL |
| CLASS SSL.sslfile |
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 might each do both reading and writing. In callback mode that means that installing either a read or a write callback might install both internally. It also means that reading in one thread while writing in another doesn't work.
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.
void SSL.sslfile(Stdio.File stream, SSL.context ctx, int|void is_client, int|void is_blocking)
Create a connection over stream , which should be an open socket or pipe. ctx is the SSL context. If is_client is set then a client-side connection is started, server-side otherwise. If is_blocking is set then the stream is initially set in blocking mode, nonblocking mode otherwise.
The backend used by stream is taken over and restored after the connection is closed (see close ). The callbacks and id in stream are overwritten.
mapping get_peer_certificate_info()
returns peer certificate information, if any.
array get_peer_certificates()
returns the peer certificate chain, if any.
int close(void|string how, void|int clean_close, void|int dont_throw)
Close the connection. Both the read and write ends are always
closed - the argument how is only for Stdio.File
compatibility and must be either "rw" or 0.
If clean_close is 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.
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.
In nonblocking mode the stream might not be closed right away and the backend might be used for a while afterwards. This means that if there's an I/O problem it might not be signalled immediately by close .
I/O errors from both reading and writing might occur in blocking mode.
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.
Stdio.File shutdown()
Shut down the SSL connection without sending any more packets. The underlying stream is returned if the connection isn't shut down already and if a nonclean close hasn't been requested.
void destroy()
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.
string read(void|int length, void|int(0..1) not_all)
Read some (decrypted) data from the connection. Works like Stdio.File.read .
I/O errors from both reading and writing might occur in blocking mode.
int write(string|array(string) data, mixed ... args)
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.
This function returns zero if attempts are made to write data during the handshake phase and the mode is nonblocking.
I/O errors from both reading and writing might occur in blocking mode.
int renegotiate()
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.
The read buffer is not cleared - a read() afterwards will
return data from both before and after the renegotiation.
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.
void set_nonblocking(void|function(void|mixed: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)
Set the stream in nonblocking mode, installing the specified callbacks. The alert callback isn't touched.
Prior to version 7.5.12, this function didn't set the accept callback.
read_oob and write_oob are currently ignored.
void set_nonblocking_keep_callbacks()
Set nonblocking mode like set_nonblocking , but don't alter any callbacks.
void set_blocking()
Set the stream in blocking mode. All but the alert callback are zapped.
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.
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.
Prior to version 7.5.12, this function didn't clear the accept callback.
void set_blocking_keep_callbacks()
Set blocking mode like set_blocking , but don't alter any callbacks.
int errno()
void set_alert_callback(function(object:void) alert)
Install a function that will be called when an alert packet is received. It doesn't affect the callback mode - it's called both from backends and from within normal function calls like read and write .
This object is part of a cyclic reference whenever this is set, just like setting any other callback.
function(object:void) query_alert_callback()
void set_accept_callback(function(void|object:int) accept)
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 sslfile object and the additional id arguments (set with set_id ).
Like the read, write and close callbacks, installing this callback implies callback mode, even after the handshake is done.
function(void|object:int) query_accept_callback()
void set_read_callback(function(void|mixed:int) read)
Install a function to be called when data is available.
function(void|mixed:int) query_read_callback()
void set_write_callback(function(void|mixed:int) write)
Install a function to be called when data can be written.
function(void|mixed:int) query_write_callback()
void set_close_callback(function(void|mixed:int) close)
Install a function to be called when the connection is closed, either normally or due to an error (use errno to retrieve it).
function(void|mixed:int) query_close_callback()
void set_id(mixed id)
mixed query_id()
void set_backend(Pike.Backend backend)
Set the backend used for the file callbacks.
Pike.Backend query_backend()
Return the backend used for the file callbacks.
string query_address(int|void arg)
int is_open()
Return 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.
Stdio.File query_stream()
Return the underlying stream.
Avoid any temptation to do
destruct(sslfile_obj->query_stream()). That almost
certainly creates more problems than it solves.
SSL.connection query_connection()
Return the SSL connection object.
SSL.context query_context()
Return the SSL context object.
| CLASS SSL.sslport |
Interface similar to Stdio.Port.
inherit Stdio.Port : socket
inherit .context : context
inherit ADT.Queue : accept_queue
| CLASS SSL.connection |
SSL packet layer. SSL.connection inherits SSL.handshake, and in addition to the state in the handshake super class, it contains the current read and write states, packet queues. This object is responsible for receiving and sending packets, processing handshake packets, and providing a clear text packages for some application.
inherit .handshake : handshake
inherit ADT.Queue : alert
inherit ADT.Queue : urgent
inherit ADT.Queue : application
void set_alert_callback(function(object:void) callback)
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.
object recv_packet(string data)
Low-level receive handler. Returns a packet, an alert, or zero if more data is needed to get a complete packet.
void send_packet(object packet, int|void priority)
Queues a packet for write. Handshake and and change cipher must use the same priority, so must application data and close_notifies.
string|int to_write()
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.
void send_close()
Initiate close.
int send_streaming_data(string data)
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.
string|int got_data(string|int s)
Main receive handler. Returns a string of received application data, or 1 if a close was received, or -1 if an error occured.
This function is intended to be called from an i/o read callback.
| CLASS SSL.alert |
Alert package.
inherit .packet : packet
void SSL.alert(int level, int description, int version, string|void message, mixed|void trace)
| CLASS SSL.https |
Dummy HTTPS server
inherit SSL.sslport : sslport
| CLASS SSL.packet |
SSL Record Layer. Handle formatting and parsing of packets.
| CLASS SSL.handshake |
SSL.handshake keeps the state relevant for SSL handshaking. This includes a pointer to a context object (which doesn't change), various buffers, a pointer to a session object (reuse or created as appropriate), and pending read and write states being negotiated.
Each connection will have two sets or read and write state: 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.
array(int) SSL.handshake.client_cert_types
array(string) SSL.handshake.client_cert_distinguished_names
a few storage variables for client certificate handling on the client side. */
string SSL.handshake.client_random
string SSL.handshake.server_random
Random cookies, sent and received with the hello-messages.
int(-1..1) handle_handshake(int type, string data, string raw)
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 hadshake is in progress, 1 if handshake is finished, and -1 if a fatal error occured. It uses the send_packet() function to transmit packets.
| CLASS SSL.session |
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.
string SSL.session.identity
Identifies the session to the server
int SSL.session.compression_algorithm
Always COMPRESSION_null.
int SSL.session.cipher_suite
Constant defining a choice of keyexchange, encryption and mac algorithm.
.Cipher.CipherSpec SSL.session.cipher_spec
Information about the encryption method derived from the cipher_suite.
int SSL.session.ke_method
Key exchange method, also derived from the cipher_suite.
string SSL.session.master_secret
48 byte secret shared between the client and the server. Used for deriving the actual keys.
mapping SSL.session.cert_data
information about the certificate in use by the peer, such as issuing authority, and verification status.
array(string) SSL.session.peer_certificate_chain
the peer certificate chain
array(string) SSL.session.certificate_chain
our certificate chain
void set_cipher_suite(int suite, int version)
Sets the proper authentication method and cipher specification for the given cipher suite and verison .
void set_compression_method(int compr)
Sets the compression method. Currently only COMPRESSION_null is supported.
array(string) generate_keys(string client_random, string server_random, array(int) version)
Generates keys appropriate for the SSL version given in version , based on the client_random and server_random .
| ||||||||||||||
array(.state) new_server_states(string client_random, string server_random, array(int) version)
Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.
| ||||||
array(.state) new_client_states(string client_random, string server_random, array(int) version)
Computes a new set of encryption states, derived from the client_random, server_random and master_secret strings.
| ||||||
| CLASS SSL.state |
A connection switches from one set of state objects to another, one or more times during its lifetime. Each state object handles a one-way stream of packets, and operates in either decryption or encryption mode.
object SSL.state.session
Information about the used algorithms.
.Cipher.MACAlgorithm SSL.state.mac
Message Authentication Code
.Cipher.CipherAlgorithm SSL.state.crypt
Encryption or decryption object.
Gmp.mpz SSL.state.seq_num
64-bit sequence number.
Alert|.packet decrypt_packet(.packet packet, int version)
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.
Alert|.packet encrypt_packet(.packet packet, int version)
Encrypts a packet (including deflating and MAC-generation).
| CLASS SSL.context |
Keeps the state that is shared by all SSL-connections for one server (or one port). It includes policy configuration, a server certificate, the server's private key(s), etc. It also includes the session cache.
Crypto.RSA SSL.context.rsa
The server's private key
Crypto.RSA SSL.context.client_rsa
The client's private key (used with client certificate authentication)
array(array(string)) SSL.context.client_certificates
An array of certificate chains a client may present to a server when client certificate authentication is requested.
function(.context:array(string)) SSL.context.client_certificate_selector
A function which will select an acceptable client certificate for presentation to a remote server. This function will receive the SSL context, an array of acceptable certificate types, and a list of DNs of acceptable certificate authorities. This function should return an array of strings containing a certificate chain, with the client certificate first, (and the root certificate last, if applicable.)
int SSL.context.auth_level
Policy for client authentication. One of SSL.Constants.AUTHLEVEL_none , SSL.Constants.AUTHLEVEL_ask and SSL.Constants.AUTHLEVEL_require .
void set_authorities(array(string) a)
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 Tools.PEM.Msg 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.
int SSL.context.require_trust
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.
array(string) get_authorities()
Get the list of allowed authorities. See set_authorities .
void set_trusted_issuers(array(array(string)) i)
Sets the list of trusted certificate issuers.
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 Tools.PEM.Msg 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.
array(array(string)) get_trusted_issuers()
Get the list of trusted issuers. See set_trusted_issuers .
int SSL.context.verify_certificates
Determines whether certificates presented by the peer are verified, or just accepted as being valid.
Crypto.RSA SSL.context.long_rsa
Crypto.RSA SSL.context.short_rsa
Temporary, non-certified, private keys, used with a server_key_exchange message. The rules are as follows:
If the negotiated cipher_suite has the "exportable" property, and short_rsa is not zero, send a server_key_exchange message with the (public part of) the short_rsa key.
If the negotiated cipher_suite does not have the exportable property, and long_rsa is not zero, send a server_key_exchange message with the (public part of) the long_rsa key.
Otherwise, dont send any server_key_exchange message.
Crypto.DSA SSL.context.dsa
Servers dsa key.
.Cipher.DHParameters SSL.context.dh_params
Parameters for dh keyexchange.
function(int:string) SSL.context.random
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.
array(string) SSL.context.certificates
The server's certificate, or a chain of X509.v3 certificates, with the server's certificate first and root certificate last.
array(int) SSL.context.preferred_auth_methods
For client authentication. Used only if auth_level is AUTH_ask or AUTH_require.
array(int) SSL.context.preferred_suites
Cipher suites we want the server to support, best first.
void rsa_mode()
Set preferred_suites to RSA based methods.
void dhe_dss_mode()
Set preferred_suites to DSS based methods.
array(int) SSL.context.preferred_compressors
Always ({ COMPRESSION_null })
int SSL.context.use_cache
Non-zero to enable cahing of sessions
int SSL.context.session_lifetime
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.
int SSL.context.max_sessions
Maximum number of sessions to keep in the cache.
.session lookup_session(string id)
Lookup a session identifier in the cache. Returns the corresponding session, or zero if it is not found or caching is disabled.
.session new_session()
Create a new session.
void record_session(.session s)
Add a session to the cache (if caching is enabled).
void purge_session(.session s)
Remove a session from the cache.
| Module SSL.Cipher |
Encryption and MAC algorithms used in SSL.
string prf(string secret, string label, string seed, int len)
ADT.struct rsa_sign(object context, string cookie, ADT.struct struct)
int(0..1) rsa_verify(object context, string cookie, ADT.struct struct, Gmp.mpz signature)
ADT.struct dsa_sign(object context, string cookie, ADT.struct struct)
ADT.struct anon_sign(object context, string cookie, ADT.struct struct)
| CLASS SSL.Cipher.CipherAlgorithm |
Cipher algorithm interface.
this_program set_encrypt_key(string)
this_program set_decrypt_key(string)
Set the key used for encryption/decryption, and enter encryption mode.
int(0..) block_size()
Return the block size for this crypto.
| CLASS SSL.Cipher.MACAlgorithm |
Message Authentication Code interface.
| CLASS SSL.Cipher.CipherSpec |
Cipher specification.
| CLASS SSL.Cipher.MACsha |
MAC using SHA.
string hash_raw(string data)
string hash(object packet, Gmp.mpz seq_num)
string hash_master(string data, string|void s)
void SSL.Cipher.MACsha(string|void s)
| CLASS SSL.Cipher.MACmd5 |
MAC using MD5.
inherit MACsha : MACsha
| CLASS SSL.Cipher.MAChmac_sha |
string hash(object packet, Gmp.mpz seq_num)
void SSL.Cipher.MAChmac_sha(string|void s)
| CLASS SSL.Cipher.MAChmac_md5 |
inherit MAChmac_sha : MAChmac_sha
void SSL.Cipher.MAChmac_md5(string|void s)
| CLASS SSL.Cipher.DES |
inherit Crypto.CBC : CBC
| CLASS SSL.Cipher.DES3 |
inherit Crypto.CBC : CBC
| CLASS SSL.Cipher.DHParameters |
Diffie-Hellman parameters.
Gmp.mpz SSL.Cipher.DHParameters.p
Gmp.mpz SSL.Cipher.DHParameters.g
Gmp.mpz SSL.Cipher.DHParameters.order
| Module SSL.Constants |
Protocol constants
| ENUM SSL.Constants.KeyExchangeType |
Key exchange methods.
constant SSL.Constants.KE_rsa
Rivest-Shamir-Adelman
constant SSL.Constants.KE_dh
Diffie-Hellman
| ENUM SSL.Constants.CompressionType |
Compression methods.
constant SSL.Constants.COMPRESSION_null
No compression.
| Module Protocols.LysKOM |
| CLASS Protocols.LysKOM.Connection |
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.
mixed XXX(mixed ... args)
object async_XXX(mixed ... args)
object async_cb_XXX(function callback, mixed ... args)
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.
int Protocols.LysKOM.Connection.protocol_level
string Protocols.LysKOM.Connection.session_software
string Protocols.LysKOM.Connection.software_version
Description of the connected server.
void Protocols.LysKOM.Connection(string server)
void Protocols.LysKOM.Connection(string server, mapping options)
The options argument is a mapping with the following members:
|
| CLASS Protocols.LysKOM.Session |
object Protocols.LysKOM.Session.user
This variable contains the Protocols.LysKOM.Session.Person that is logged in.
void Protocols.LysKOM.Session(string server)
void Protocols.LysKOM.Session(string server, mapping options)
Initializes the session object, and opens a connection to that server.
options is a mapping of options:
|
Connection
Text text(int no)
Returns the text no .
Person person(int no)
Returns the Person no .
Conference conference(int no)
Returns conference number no .
array(ProtocolTypes.ConfZInfo) try_complete_person(string orig)
Runs a LysKOM completion on the given string, returning an array of confzinfos of the match.
object login(int user_no, string password)
object login(int user_no, string password, int invisible)
Performs a login. Throws a lyskom error if unsuccessful.
The session object logged in.
object create_person(string name, string password)
Create a person, which will be logged in. returns the new person object
this_program logout()
Logouts from the server. returns the called object
object create_text(string subject, string body, mapping options)
object create_text(string subject, string body, mapping options, function callback, mixed ... extra)
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:
|
The items above marked with '*' are only available on protocol 10 servers. A LysKOM error will be thrown if the call fails.
Conference.create_text() , Text.comment() , Text.footnote()
object|void send_message(string textstring, mapping options)
Sends a message.
options is a mapping that may contain:
|
void register_async_message_callback(function(int:void) cb)
| CLASS Protocols.LysKOM.Session.AuxItemInput |
Undocumented
inherit ProtocolTypes.AuxItemInput : AuxItemInput
| CLASS Protocols.LysKOM.Session.AuxItems |
Undocumented
| CLASS Protocols.LysKOM.Session.Text |
All variables in this class is read only.
Undocumented
int Protocols.LysKOM.Session.Text.no
The text number, as spicified to create .
object Protocols.LysKOM.Session.Text.err
Undocumented
void Protocols.LysKOM.Session.Text(string textnumber)
Initializes a Text object.
void mark_as_read()
Undocumented.
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
Undocumented
string Protocols.LysKOM.Session.Text.text
The actual text (or body if you wish).
string Protocols.LysKOM.Session.Text.subject
The message subject.
string Protocols.LysKOM.Session.Text.author
The author of the text.
mixed Protocols.LysKOM.Session.Text.misc
Misc info, including what conferences the message is posted to.
Needs a more complete description.
int Protocols.LysKOM.Session.Text.marks
The number of marks on this text.
mixed Protocols.LysKOM.Session.Text.creation_time
The time the text was created on the server.
| CLASS Protocols.LysKOM.Session.Membership |
All variables in this class is read only.
object Protocols.LysKOM.Session.Membership.last_time_read
int(0..255) Protocols.LysKOM.Session.Membership.priority
int Protocols.LysKOM.Session.Membership.last_text_read
array(int) Protocols.LysKOM.Session.Membership.read_texts
object Protocols.LysKOM.Session.Membership.added_at
multiset(string) Protocols.LysKOM.Session.Membership.type
int Protocols.LysKOM.Session.Membership.position
object Protocols.LysKOM.Session.Membership.conf
int number_unread()
void query_read_texts()
array(object) unread_texts()
| CLASS Protocols.LysKOM.Session.Person |
int Protocols.LysKOM.Session.Person.no
void Protocols.LysKOM.Session.Person(int no)
mixed Protocols.LysKOM.Session.Person.prefetch_stat
mixed Protocols.LysKOM.Session.Person.prefetch_conf
mixed Protocols.LysKOM.Session.Person.prefetch_membership
Undocumented
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
Undocumented
| CLASS Protocols.LysKOM.Session.Conference |
void Protocols.LysKOM.Session.Conference(int no)
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
Undocumented
| Module Protocols.LysKOM.ProtocolTypes |
Data types as defined by the LysKOM protocol specification.
| Module Protocols.LysKOM.Request |
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 |
This is the main request class. All lyskom request classes inherit this class.
void async(mixed ... args)
mixed sync(mixed ... args)
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.
void _async(int call, mixed_data)
mixed _sync(int call, mixed_data)
Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. These are called by async and sync respectively.
mixed _reply(object|array what)
mixed reply(object|array what)
_reply() is called as callback to evaluate the result, and calls reply() in itself to do the real work.
mixed `()()
Wait for the call to finish.
int(0..1) Protocols.LysKOM.Request._Request.ok
Tells if the call has executed ok
object Protocols.LysKOM.Request._Request.error
How the call failed.
The call has completed if (ok||error).
| Module Protocols.DNS |
Domain Name System RFC 1034, RFC 1035 and RFC 2308
void async_ip_to_host(string ip, function cb, mixed ... cba)
void async_host_to_ip(string host, function cb, mixed ... cba)
void async_get_mx_all(string host, function cb, mixed ... cba)
void async_get_mx(string host, function cb, mixed ... cba)
array gethostbyname(string host)
array gethostbyaddr(string host)
string get_mx(string host)
string get_primary_mx(string host)
| ENUM Protocols.DNS.ResourceClass |
Resource classes
constant Protocols.DNS.C_IN
Class Internet
constant Protocols.DNS.C_CS
Class CSNET (Obsolete)
constant Protocols.DNS.C_CH
Class CHAOS
constant Protocols.DNS.C_HS
Class Hesiod
constant Protocols.DNS.C_ANY
Class ANY
| ENUM Protocols.DNS.EntryType |
Entry types
constant Protocols.DNS.T_A
Type - host address
constant Protocols.DNS.T_NS
Type - authoritative name server
constant Protocols.DNS.T_MD
Type - mail destination (Obsolete - use MX)
constant Protocols.DNS.T_MF
Type - mail forwarder (Obsolete - use MX)
constant Protocols.DNS.T_CNAME
Type - canonical name for an alias
constant Protocols.DNS.T_SOA
Type - start of a zone of authority
constant Protocols.DNS.T_MB
Type - mailbox domain name (EXPERIMENTAL)
constant Protocols.DNS.T_MG
Type - mail group member (EXPERIMENTAL)
constant Protocols.DNS.T_MR
Type - mail rename domain name (EXPERIMENTAL)
constant Protocols.DNS.T_NULL
Type - null RR (EXPERIMENTAL)
constant Protocols.DNS.T_WKS
Type - well known service description
constant Protocols.DNS.T_PTR
Type - domain name pointer
constant Protocols.DNS.T_HINFO
Type - host information
constant Protocols.DNS.T_MINFO
Type - mailbox or mail list information
constant Protocols.DNS.T_MX
Type - mail exchange
constant Protocols.DNS.T_TXT
Type - text strings
constant Protocols.DNS.T_AAAA
Type - IPv6 address record (RFC 1886, deprecated)
constant Protocols.DNS.T_LOC
Type - Location Record (RFC 1876)
constant Protocols.DNS.T_SRV
Type - Service location record (RFC 2782)
constant Protocols.DNS.T_NAPTR
Type - NAPTR (RFC 3403)
constant Protocols.DNS.T_A6
Type - IPv6 address record (RFC 2874, incomplete support)
constant Protocols.DNS.T_SPF
Type - SPF - Sender Policy Framework (RFC 4408)
| CLASS Protocols.DNS.protocol |
Low level DNS protocol
string mkquery(string|mapping dnameorquery, int|void cl, int|void type)
create a DNS query PDU
record class such as Protocols.DNS.C_IN
query type such Protocols.DNS.T_A
data suitable for use with Protocols.DNS.client.do_sync_query
// generate a query PDU for a address lookup on the hostname pike.ida.liu.se string q=Protocols.DNS.protocol()->mkquery("pike.ida.liu.se", Protocols.DNS.C_IN, Protocols.DNS.T_A);
array decode_entries(string s, int num, array(int) next)
Decode a set of entries from an answer.
Encoded entries.
Number of entires in s .
Array with a single element containing the start position in s on entry and the continuation position on return.
Returns an array of mappings describing the decoded entires:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| CLASS Protocols.DNS.server |
Implements a Domain Name Service (DNS) server.
inherit Stdio.UDP : udp
inherit protocol : protocol
mapping reply_query(mapping query, mapping udp_data)
Reply to a query (stub).
Parsed query.
Raw UDP data.
Overload this function to implement the proper lookup.
Returns 0 (zero) on failure, or a result mapping on success:
| ||||||||||||||||||
| CLASS Protocols.DNS.client |
Synchronous DNS client.
inherit protocol : protocol
void Protocols.DNS.client()
void Protocols.DNS.client(void|string|array server, void|int|array domain)
mapping do_sync_query(string s)
perform a syncronous query
result of Protocols.DNS.protocol.mkquery
mapping containing query result or 0 on failure/timeout
// perform a hostname lookup, results stored in r->an object d=Protocols.DNS.client(); mapping r=d->do_sync_query(d->mkquery("pike.ida.liu.se", C_IN, T_A));
array gethostbyname(string hostname)
Queries the host name from the default or given DNS server. The result is an array with three elements,
An array with the requested information about the specified host.
| ||||||||
Prior to Pike 7.7 this function only returned IPv4 addresses.
array getsrvbyname(string service, string protocol, string|void name)
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:
An array with the requested information about the specified service.
| ||||||||||
array gethostbyaddr(string hostip)
Queries the host name or ip from the default or given DNS server. The result is an array with three elements,
The requested data about the specified host.
| ||||||||
string get_primary_mx(string hostname)
Queries the primary mx for the host.
Returns the hostname of the primary mail exchanger.
| Module Protocols |
| Module Protocols.LysKOM |
| CLASS Protocols.LysKOM.Connection |
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.
mixed XXX(mixed ... args)
object async_XXX(mixed ... args)
object async_cb_XXX(function callback, mixed ... args)
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.
int Protocols.LysKOM.Connection.protocol_level
string Protocols.LysKOM.Connection.session_software
string Protocols.LysKOM.Connection.software_version
Description of the connected server.
void Protocols.LysKOM.Connection(string server)
void Protocols.LysKOM.Connection(string server, mapping options)
The options argument is a mapping with the following members:
|
| CLASS Protocols.LysKOM.Session |
object Protocols.LysKOM.Session.user
This variable contains the Protocols.LysKOM.Session.Person that is logged in.
void Protocols.LysKOM.Session(string server)
void Protocols.LysKOM.Session(string server, mapping options)
Initializes the session object, and opens a connection to that server.
options is a mapping of options:
|
Connection
Text text(int no)
Returns the text no .
Person person(int no)
Returns the Person no .
Conference conference(int no)
Returns conference number no .
array(ProtocolTypes.ConfZInfo) try_complete_person(string orig)
Runs a LysKOM completion on the given string, returning an array of confzinfos of the match.
object login(int user_no, string password)
object login(int user_no, string password, int invisible)
Performs a login. Throws a lyskom error if unsuccessful.
The session object logged in.
object create_person(string name, string password)
Create a person, which will be logged in. returns the new person object
this_program logout()
Logouts from the server. returns the called object
object create_text(string subject, string body, mapping options)
object create_text(string subject, string body, mapping options, function callback, mixed ... extra)
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:
|
The items above marked with '*' are only available on protocol 10 servers. A LysKOM error will be thrown if the call fails.
Conference.create_text() , Text.comment() , Text.footnote()
object|void send_message(string textstring, mapping options)
Sends a message.
options is a mapping that may contain:
|
void register_async_message_callback(function(int:void) cb)
| CLASS Protocols.LysKOM.Session.AuxItemInput |
Undocumented
inherit ProtocolTypes.AuxItemInput : AuxItemInput
| CLASS Protocols.LysKOM.Session.AuxItems |
Undocumented
| CLASS Protocols.LysKOM.Session.Text |
All variables in this class is read only.
Undocumented
int Protocols.LysKOM.Session.Text.no
The text number, as spicified to create .
object Protocols.LysKOM.Session.Text.err
Undocumented
void Protocols.LysKOM.Session.Text(string textnumber)
Initializes a Text object.
void mark_as_read()
Undocumented.
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
Undocumented
string Protocols.LysKOM.Session.Text.text
The actual text (or body if you wish).
string Protocols.LysKOM.Session.Text.subject
The message subject.
string Protocols.LysKOM.Session.Text.author
The author of the text.
mixed Protocols.LysKOM.Session.Text.misc
Misc info, including what conferences the message is posted to.
Needs a more complete description.
int Protocols.LysKOM.Session.Text.marks
The number of marks on this text.
mixed Protocols.LysKOM.Session.Text.creation_time
The time the text was created on the server.
| CLASS Protocols.LysKOM.Session.Membership |
All variables in this class is read only.
object Protocols.LysKOM.Session.Membership.last_time_read
int(0..255) Protocols.LysKOM.Session.Membership.priority
int Protocols.LysKOM.Session.Membership.last_text_read
array(int) Protocols.LysKOM.Session.Membership.read_texts
object Protocols.LysKOM.Session.Membership.added_at
multiset(string) Protocols.LysKOM.Session.Membership.type
int Protocols.LysKOM.Session.Membership.position
object Protocols.LysKOM.Session.Membership.conf
int number_unread()
void query_read_texts()
array(object) unread_texts()
| CLASS Protocols.LysKOM.Session.Person |
int Protocols.LysKOM.Session.Person.no
void Protocols.LysKOM.Session.Person(int no)
mixed Protocols.LysKOM.Session.Person.prefetch_stat
mixed Protocols.LysKOM.Session.Person.prefetch_conf
mixed Protocols.LysKOM.Session.Person.prefetch_membership
Undocumented
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
Undocumented
| CLASS Protocols.LysKOM.Session.Conference |
void Protocols.LysKOM.Session.Conference(int no)
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
Undocumented
| Module Protocols.LysKOM.ProtocolTypes |
Data types as defined by the LysKOM protocol specification.
| Module Protocols.LysKOM.Request |
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 |
This is the main request class. All lyskom request classes inherit this class.
void async(mixed ... args)
mixed sync(mixed ... args)
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.
void _async(int call, mixed_data)
mixed _sync(int call, mixed_data)
Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. These are called by async and sync respectively.
mixed _reply(object|array what)
mixed reply(object|array what)
_reply() is called as callback to evaluate the result, and calls reply() in itself to do the real work.
mixed `()()
Wait for the call to finish.
int(0..1) Protocols.LysKOM.Request._Request.ok
Tells if the call has executed ok
object Protocols.LysKOM.Request._Request.error
How the call failed.
The call has completed if (ok||error).
| Module Protocols.X |
| Module Protocols.X.Extensions |
| CLASS Protocols.X.Extensions.extension |
an abstract class used to provide features for implimenting X11 extensions. Provides no useful functionality on its own.
int init(object d)
initialize the extension.
An object of type Protocols.X.Xlib.Display
| CLASS Protocols.X.Extensions.XTEST |
Provides support for the X11 XTEST extension.
inherit extension : extension
void Protocols.X.Extensions.XTEST()
Create object.
int init(object display)
Initialize the XTEST extension. Returns 1 if successful.
Protocols.X.Display object
void XTestFakeInput(string event_type, int detail, int delay, object|void window, int|void xloc, int|void yloc)
Send a synthetic event to an X server.
Type of event to send. Possible values: KeyPress: 2, KeyRelease: 3, ButtonPress: 4, ButtonRelease: 5, MotionNotify: 6
Button (for Button events) or Keycode (for Key events) to send
Delay before the X server simulates event. 0 indicates zero delay.
Window object that a motion event occurrs in. If no window is provided, the root window will be used.
For motion events, this is the relative X distance or absolute X coordinates.
For motion events, this is the relative Y distance or absolute Y coordinates.
void XTestGrabControl(int impervious)
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.
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.
| Module Protocols.HTTP |
.Query do_method(string method, string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con, void|string data)
Low level HTTP call method.
The HTTP method to use, e.g. "GET".
The URL to perform method on. Should be a complete URL,
including protocol, e.g. "https://pike.ida.liu.se/".
Calls http_encode_query and appends the result to the URL.
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.
Old connection object.
Data payload to be transmitted in the request.
do_sync_method()
void do_async_method(string method, string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, Protocols.HTTP.Query con, void|string data)
Low level asynchronous HTTP call method.
The HTTP method to use, e.g. "GET".
The URL to perform method on. Should be a complete URL,
including protocol, e.g. "https://pike.ida.liu.se/".
Calls http_encode_query and appends the result to the URL.
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.
Previously initialized connection object. In particular the callbacks must have been set (Query.set_callbacks() ).
Data payload to be transmitted in the request.
do_method() , Query.set_callbacks()
.Query get_url(string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
.Query put_url(string|Standards.URI url, void|string file, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
.Query delete_url(string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
array(string) get_url_nice(string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
string get_url_data(string|Standards.URI url, void|mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
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.
.Query post_url(string|Standards.URI url, mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
Similar to get_url , except that query variables is sent as a POST request instead of a GET request.
array(string) post_url_nice(string|Standards.URI url, mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
Similar to get_url_nice , except that query variables is sent as a POST request instead of a GET request.
string post_url_data(string|Standards.URI url, mapping(string:int|string) query_variables, void|mapping(string:string|array(string)) request_headers, void|Protocols.HTTP.Query con)
Similar to get_url_data , except that query variables is sent as a POST request instead of a GET request.
string http_encode_query(mapping(string:int|string|array(string)) variables)
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"
string percent_encode(string s)
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.
string percent_decode(string s)
Decodes URI-style %XX encoded chars in the given string.
percent_encode , uri_decode
This function currently does not accept wide string input, which is necessary to work as the reverse of iri_encode .
string uri_encode(string s)
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.
uri_decode , uri_encode_invalids , iri_encode
string uri_encode_invalids(string s)
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.
The characters in the URI reserved set are: :, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ;, =. In addition, this function doesn't touch the escape char %.
uri_decode , uri_encode
string uri_decode(string s)
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 .
uri_encode , uri_encode_invalids
string iri_encode(string s)
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.
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.
percent_decode , uri_encode
string uri_normalize(string s)
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.
uri_decode , uri_encode , iri_normalize
string iri_normalize(string s)
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.
iri_decode , uri_normalize
string quoted_string_encode(string s)
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.
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.
quoted_string_decode
string quoted_string_decode(string s)
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.
quoted_string_encode
__deprecated__ string http_encode_string(string in)
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__ string http_encode_cookie(string f)
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__ string unentity(string s)
Helper function for replacing HTML entities with the corresponding unicode characters.
| CLASS Protocols.HTTP.Query |
Open and execute an HTTP query.
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.ida.liu.se", 80, "HEAD / HTTP/1.0"); return -1; }
int Protocols.HTTP.Query.errno
Errno copied from the connection.
int Protocols.HTTP.Query.ok
Tells if the connection is successfull.
mapping Protocols.HTTP.Query.headers
Headers as a mapping. All header names are in lower case, for convinience.
string Protocols.HTTP.Query.protocol
Protocol string, ie "HTTP/1.0".
int Protocols.HTTP.Query.status
string Protocols.HTTP.Query.status_desc
Status number and description (eg 200 and "ok").
mapping Protocols.HTTP.Query.hostname_cache
Set this to a global mapping if you want to use a cache, prior of calling *request().
Protocols.HTTP.Query set_callbacks(function request_ok, function request_fail, mixed ... extra)
Protocols.HTTP.Query async_request(string server, int port, string query)
Protocols.HTTP.Query async_request(string server, int port, string query, mapping headers, string|void data)
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 the called object
Protocols.HTTP.Query thread_request(string server, int port, string query)
Protocols.HTTP.Query thread_request(string server, int port, string query, mapping headers, void|string data)
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 the called object.
int `()()
Wait for connection to complete.
Returns 1 on successfull connection, 0 on failure.
string data(int|void max_length)
Gives back the data as a string.
string unicode_data()
Gives back data, but decoded according to the content-type character set.
data
int downloaded_bytes()
Gives back the number of downloaded bytes.
int total_bytes()
Gives back the size of a file if a content-length header is present and parsed at the time of evaluation. Otherwise returns -1.
array cast("array")
| ||||||||||||
mapping cast("mapping")
The header mapping ORed with the following mapping.
|
string cast("string")
Gives back the answer as a string.
Protocols.HTTP.Query.PseudoFile file()
Protocols.HTTP.Query.PseudoFile file(mapping newheaders, void|mapping removeheaders)
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.
datafile()
Protocols.HTTP.Query.PseudoFile datafile()
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.
file()
void async_fetch(function callback, mixed ... extra)
Fetch all data in background.
timed_async_fetch() , async_request() , set_callbacks()
void timed_async_fetch(function(object:void) ok_callback, function(object:void) fail_callback, mixed ... extra)
Like async_fetch() , except with a timeout and a corresponding fail callback function.
async_fetch() , async_request() , set_callbacks()
| CLASS Protocols.HTTP.Session |
int Protocols.HTTP.Session.follow_redirects
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.
Loops will currently not be detected, only the limit works to stop loops.
Request.follow_redirects
mapping Protocols.HTTP.Session.default_headers
Default HTTP headers.
void set_http_cookie(string cookie, Standards.URI at)
Parse and set a cookie received in the HTTP protocol. The cookie will be checked against current security levels et al.
void set_cookie(Cookie cookie, Standards.URI who)
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.
string encode_cookies()
void decode_cookies(string data, void no_clear)
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.
array(string) get_cookies(Standards.URI|SessionURL for_url, void|int(0..1) no_delete)
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.
mapping Protocols.HTTP.Session.hostname_cache
Cache of hostname to IP lookups. Given to and used by the Query objects.
int|float Protocols.HTTP.Session.time_to_keep_unused_connections
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.
int Protocols.HTTP.Session.maximum_connections_per_server
Maximum number of connections to the same server. Used only by async requests. Defaults to 10 connections.
int Protocols.HTTP.Session.maximum_total_connections
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.
int Protocols.HTTP.Session.maximum_connection_reuse
Maximum times a connection is reused. Defaults to 1000000. <2 means no reuse at all.
Query give_me_connection(Standards.URI url)
Request a Query object suitable to use for the given URL. This may be a reused object from a keep-alive connection.
void return_connection(Standards.URI url, Query query)
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.
Request get_url(URL url, void|mapping query_variables)
Request post_url(URL url, mapping query_variables)
Request put_url(URL url, string file, void|mapping query_variables)
Request delete_url(URL url, void|mapping query_variables)
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.
array(string) get_url_nice(URL url, mapping query_variables)
string get_url_data(URL url, mapping query_variables)
array(string) post_url_nice(URL url, mapping query_variables)
string post_url_data(URL url, mapping query_variables)
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.
Request async_get_url(URL url, void|mapping query_variables, function callback_headers_ok, function callback_data_ok, function callback_fail, mixed ... callback_arguments)
Request async_put_url(URL url, void|string file, void|mapping query_variables, function callback_headers_ok, function callback_data_ok, function callback_fail, mixed ... callback_arguments)
Request async_delete_url(URL url, void|mapping query_variables, function callback_headers_ok, function callback_data_ok, function callback_fail, mixed ... callback_arguments)
Request async_post_url(URL url, mapping query_variables, function callback_headers_ok, function callback_data_ok, function callback_fail, mixed ... callback_arguments)
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.
| CLASS Protocols.HTTP.Session.Request |
Request
Query Protocols.HTTP.Session.Request.con
Raw connection object
Standards.URI Protocols.HTTP.Session.Request.url_requested
URL requested (set by prepare_method). This will update according to followed redirects.
int Protocols.HTTP.Session.Request.follow_redirects
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.
Loops will currently not be detected, only the limit works to stop loops.
function(string:mixed) Protocols.HTTP.Session.Request.cookie_encountered
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.
array(string|int|mapping) prepare_method(string method, URL url, void|mapping query_variables, void|mapping extra_headers, void|string data)
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).
Request do_sync(array(string|int|mapping) args)
Perform a request synchronously. Get arguments from prepare_method .
0 upon failure, this object upon success
prepare_method , do_async , do_thread
Request do_thread(array(string|int|mapping) args)
Start a request in the background, using a thread. Call wait to wait for the thread to finish. Get arguments from prepare_method .
The called object.
prepare_method , do_sync , do_async , wait
do_thread does not rerun redirections automatically
Request wait()
Wait for the request thread to finish.
0 upon failure, or the called object upon success.
do_thread
void set_callbacks(function(mixed ... :mixed) headers, function(mixed ... :mixed) data, function(mixed ... :mixed) fail, mixed ... callback_arguments)
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.
Request do_async(array(string|int|mapping) args)
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 .
The called object.
set_callbacks , prepare_method , do_sync , do_thread
void destroy()
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.
| CLASS Protocols.HTTP.Session.SessionURL |
Class to store URL+referer
inherit Standards.URI : URI
URL Protocols.HTTP.Session.SessionURL.referer
the referer to this URL
void Protocols.HTTP.Session.SessionURL(URL uri, URL base_uri, URL _referer)
instantiate a SessionURL object; when fed to Protocols.HTTP.Session calls, will add referer to the HTTP handshaking variables
| Module Protocols.HTTP.Server |
constant Protocols.HTTP.Server.HeaderParser
Fast HTTP header parser.
constant Protocols.HTTP.Server.http_decode_string
mapping(string:string|array(string)) http_decode_urlencoded_query(string query, void|mapping dest)
Decodes an URL-encoded query into a mapping.
string extension_to_type(string extension)
Looks up the file extension in a table to return a suitable MIME type.
string filename_to_type(string filename)
Looks up the file extension in a table to return a suitable MIME type.
string http_date(int time)
Makes a time notification suitable for the HTTP protocol.
The time in seconds since the 00:00:00 UTC, January 1, 1970
The date in the HTTP standard date format. Example : Thu, 03 Aug 2000 05:40:39 GMT
int http_decode_date(string data)
Decode a HTTP date to seconds since 1970 (UTC)
zero (UNDEFINED) if the given string isn't a HTTP date
| CLASS Protocols.HTTP.Server.Request |
string Protocols.HTTP.Server.Request.raw
raw unparsed full request (headers and body)
string Protocols.HTTP.Server.Request.body_raw
raw unparsed body of the request (raw minus request line and headers)
string Protocols.HTTP.Server.Request.request_raw
full request line (request_type + full_query + protocol )
string Protocols.HTTP.Server.Request.request_type
HTTP request method, eg. POST, GET, etc.
string Protocols.HTTP.Server.Request.full_query
full resource requested, including attached GET query
string Protocols.HTTP.Server.Request.not_query
resource requested minus any attached query
string Protocols.HTTP.Server.Request.query
query portion of requested resource, starting after the first "?"
string Protocols.HTTP.Server.Request.protocol
request protocol and version, eg. HTTP/1.0
mapping(string:string|array(string)) Protocols.HTTP.Server.Request.request_headers
all headers included as part of the HTTP request, ie content-type.
mapping(string:string|array(string)) Protocols.HTTP.Server.Request.variables
all variables included as part of a GET or POST request.
mapping(string:string) Protocols.HTTP.Server.Request.cookies
cookies set by client
mapping Protocols.HTTP.Server.Request.misc
external use only
int Protocols.HTTP.Server.Request.send_timeout_delay
send timeout (no activity for this period with data in send buffer) in seconds, default is 180
int Protocols.HTTP.Server.Request.connection_timeout_delay
connection timeout, delay until connection is closed while waiting for the correct headers:
void response_and_finish(mapping m, function|void _log_cb)
return a properly formatted response to the HTTP client
Contains elements for generating a response to the client.
|
int sent_data()
Returns the amount of data sent.
| CLASS Protocols.HTTP.Server.Port |
The simplest server possible. Binds a port and calls a callback with Server.Request objects.
void Protocols.HTTP.Server.Port(function(.Request:void) callback)
void Protocols.HTTP.Server.Port(function(.Request:void) callback, int portno, void|string interface)
void close()
Closes the HTTP port.
| CLASS Protocols.HTTP.Server.SSLPort |
The simplest SSL server possible. Binds a port and calls a callback with Request objects.
void Protocols.HTTP.Server.SSLPort(function(Request:void) _callback, void|int _portno, void|string _interface, void|string key, void|string|array certificate)
Create a HTTPS (HTTP over SSL) server.
The function run when a request is received. takes one argument of type Request .
The port number to bind to, defaults to 443.
The interface address to bind to.
An optional SSL secret key, provided in binary format, such as that created by Standards.PKCS.RSA.private_key() .
An optional SSL certificate or chain of certificates with the host certificate first, provided in binary format.
void close()
Closes the HTTP port.
void new_connection()
The port accept callback
| CLASS Protocols.HTTP.Server.SSLPort.MySSLPort |
inherit SSL.sslport : sslport
void set_default_keycert()
void set_key(string skey)
void set_certificate(string|array(string) certificate)
| Module Protocols.XMLRPC |
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.
Translation rules for conversions from XML-RPC datatypes to Pike datatypes:
XML-RPC <i4>, <int> and <boolean> are
translated to Pike int.
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.
The XML-RPC <dateTime.iso8601> datatype does not assume any time zone, but local time is always used in the conversion to Calendar objects.
Call decode_call(string xml_input)
Decodes a XML-RPC representation of a function call and returns a Call object.
Call
array|Fault decode_response(string xml_input)
Decodes a XML-RPC representation of a response and returns an array containing response values, or a Fault object.
Fault
string encode_call(string method_name, array params)
Encodes a function call with the name method_name and the arguments params and returns the XML-RPC string representation.
string encode_response(array params)
Encodes a response containing the multiple values in params and returns the XML-RPC string representation.
string encode_response_fault(int fault_code, string fault_string)
Encodes a response fault containing a fault_code and a fault_string and returns the XML-RPC string representation.
| CLASS Protocols.XMLRPC.Call |
Represents a function call made to a XML-RPC server.
decode_call()
string Protocols.XMLRPC.Call.method_name
array Protocols.XMLRPC.Call.paramsvoid Protocols.XMLRPC.Call(string method_name, array params)
int Protocols.XMLRPC.Call.method_name
Represents <methodName> in the XML-RPC standard.
array Protocols.XMLRPC.Call.params
Represents <params> in the XML-RPC standard where all datatypes have been converted to equivalent or similar datatypes in Pike.
| CLASS Protocols.XMLRPC.Fault |
Represents a fault response which can be one of the return values from a XML-RPC function call.
decode_response()
int Protocols.XMLRPC.Fault.fault_code
string Protocols.XMLRPC.Fault.fault_stringvoid Protocols.XMLRPC.Fault(int fault_code, string fault_string)
int Protocols.XMLRPC.Fault.fault_code
Represents faultCode in the XML-RPC standard.
int Protocols.XMLRPC.Fault.fault_string
Represents faultString in the XML-RPC standard.
| CLASS Protocols.XMLRPC.Client |
This class implements an XML-RPC client that uses HTTP transport.
> 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" }) })
string|Standards.URI Protocols.XMLRPC.Client.urlvoid Protocols.XMLRPC.Client(string|Standards.URI url)
| CLASS Protocols.XMLRPC.AsyncClient |
This class implements an XML-RPC client that uses HTTP transport using non blocking sockets.
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;
| Module Protocols.IRC |
| CLASS Protocols.IRC.Person |
Abstract class for a person.
string Protocols.IRC.Person.nick
User nickname, e.g. "Mirar".
string Protocols.IRC.Person.user
User name, e.g. "mirar".
string Protocols.IRC.Person.ip
User domain, e.g. "mistel.idonex.se".
int Protocols.IRC.Person.last_action
Time of last action, represented as posix time.
| CLASS Protocols.IRC.Channel |
Abstract class for a IRC channel.
string Protocols.IRC.Channel.name
The name of the channel.
| CLASS Protocols.IRC.Client |
void Protocols.IRC.Client(string server, void|mapping(string:mixed) options)
The IRC server to connect to.
An optional mapping with additional IRC client options.
|
void close()
Closes the connection to the server.
| Module Protocols.Bittorrent |
| CLASS Protocols.Bittorrent.Torrent |
Bittorrent peer - download and share. Read more about bittorrent at http://bitconjurer.org/BitTorrent/introduction.html
The smallest usable torrent downloader. As first argument, it expects a filename to a .torrent file.
int main(int ac,array am) { // initialize Torrent from file: Protocols.Bittorrent.Torrent t=Protocols.Bittorrent.Torrent(); t->load_metainfo(am[1]);
// Callback when download status changes: // t->downloads_update_status=...;
// Callback when pieces status change (when we get new stuff): // t->pieces_update_status=...;
// Callback when peer status changes (connect, disconnect, choked...): // t->peer_update_status=...;
// Callback when download is completed: t->download_completed_callback= lambda() { call_out(exit,3600,0); // share for an hour, then exit };
// Callback to print warnings (same args as sprintf): // t->warning=werror;
// type of progress function used below: void progress(int n,int of) { /* ... */ };
// Initiate targets from Torrent, // if target was created, no need to verify: if (t->fix_targets(1,0,progress)==1) t->verify_targets(progress);
// Open port to listen on, // we want to do this to be able to talk to firewalled peers: t->open_port(6881);
// Ok, start calling tracker to get peers, // and tell about us: t->start_update_tracker();
// Finally, start the download: t->start_download();
return -1; }
function(.Peer:int(0..1)) Protocols.Bittorrent.Torrent.do_we_strangle
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.
function Protocols.Bittorrent.Torrent.pieces_update_status
If set, called when we got another piece downloaded (no args).
function Protocols.Bittorrent.Torrent.downloads_update_status
If set, called when we start to download another piece (no args).
function Protocols.Bittorrent.Torrent.peer_update_status
If set, called when peer status changes.
function Protocols.Bittorrent.Torrent.download_completed_callback
If set, called when download is completed.
function(string:void|mixed) Protocols.Bittorrent.Torrent.warning
Called if there is a protocol error.
void load_metainfo(string filename)
Loads the metainfo from a file.
int fix_targets(void|int(-1..2) allocate, void|string base_filename, void|function(int:void) progress_callback)
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.
Determines allocation procedure if the file doesn't exist:
|
A new base filename to substitute the metainfo base target filename with.
|
void verify_targets(void|function(int:void) progress_callback)
Verify the file and fill file_got (necessary after load_info, but needs open_file before this call). [ progress_callback(at chunk,total chunks) ]
void open_port(void|int port)
Open the port we're listening on.
int bytes_done()
Calculate the bytes successfully downloaded (full pieces).
int bytes_left()
Calculate the bytes left to download.
void update_tracker(void|string event, void|int contact)
Contact and update the tracker with current status will fill the peer list.
void start_update_tracker(void|int interval)
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.
void stop_update_tracker(void|string event)
Stops updating the tracker; will send the event as a last event, if set. It will not contact new peers.
void contact_peers(void|int n)
Contact all or n peers.
string file_got_bitfield()
Returns the file got field as a string bitfield (cached).
void start_download()
Initiate the downloading scheme.
| CLASS Protocols.Bittorrent.Torrent.Target |
Each bittorrent has one or more target files. This represents one of those.
string Protocols.Bittorrent.Torrent.Target.base
int Protocols.Bittorrent.Torrent.Target.length
int Protocols.Bittorrent.Torrent.Target.offset
void|array Protocols.Bittorrent.Torrent.Target.pathvoid Protocols.Bittorrent.Torrent.Target(string base, int length, int offset, void|array path)
| CLASS Protocols.Bittorrent.Tracker |
int(0..) Protocols.Bittorrent.Tracker.interval
The query interval reported back to clients. Defaults to
1800.
int(0..1) Protocols.Bittorrent.Tracker.dynamic_add_torrents
Allow clients to dynamically add torrents to the tracker.
void add_torrent(string id)
Add a torrent to the tracker.
The info hash of the torrent file.
string announce(mapping args, string ip)
Handles HTTP announce queries to the tracker.
string scrape(mapping args)
Returns the result of a scrape query.
| CLASS Protocols.Bittorrent.Peer |
int is_connectable()
Returns true if we can connect to this peer, when new or disconnected but not fatally.
int is_online()
Returns true if this peer is online and connected.
int is_completed()
Returns true if this peer is completed, as in has downloaded everything already - and we shouldn't need to upload to get stuff.
int is_available()
Returns true if this peer is available, as in we can use it to download stuff.
int is_activated()
Returns true if this peer is activated, as in we're downloading from it.
int is_strangled()
Returns true if this peer is strangled; as in we don't want to upload more, because we're not getting any back.
int is_choked()
Returns true if this peer is choking, as in doesn't send more data to us.
multiset(int) downloading_pieces()
Returns as multiset what this peer is downloading.
void connect()
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).
void disconnect()
Disconnect a peer.
Does nothing if we aren't online.
status/mode will change to "disconnected",1 if we were online.
void send_have(int n)
Send a have message to tell I now have piece n. Ignored if not online.
void request(int piece, int offset, int bytes, function(int:void|mixed) callback)
Called to request a chunk from this peer.
void status(string type, void|int|string data)
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.Generator |
Generate a .torrent binary string from files in the filesystem
// 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; }
inherit .Torrent : Torrent
void Protocols.Bittorrent.Generator(void|string base, void|int piece_size)
Create a generator.
The base filename/path in the torrent.
The size of the pieces that the SHA hashes are calculated on. Default 262144 and this value should probably be 2^n.
this_program add_announce(string|array(string) announce_url)
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.
this_program add_file(string path, void|string filename)
Add a file to the torrent. The second argument is what the file will be called in the torrent.
this_program add_directory_tree(string path, void|string dirbase)
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.
this_program add(string path, void|string base)
Add a file, or a directory tree to the torrent. This will call add_directory_tree or add_file.
void build_sha1s(void|function(int:void) progress_callback)
Build the SHA hashes from the files.
string digest(void|function(int:void) progress_callback)
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 .
| CLASS Protocols.Bittorrent.Port |
void Protocols.Bittorrent.Port(.Torrent _parent)
Bind a port for this Torrent.
| Module Protocols.Bittorrent.Bencoding |
array(string|int|array|mapping) _decode(string what)
Decodes a Bittorrent bencoded data chunk.
| ||||||
string|int|array|mapping decode(string what)
Decodes a Bittorrent bencoded data chunk and ignores the remaining string. Returns UNDEFINED if the data is incomplete.
string encode(string|int|array|mapping data)
Encodes a Bittorrent bencoded data chunk.
string bits2string(array(int(0..1)) v)
Convert an array of int(0..1) to a Bittorrent style
bitstring. Input will be padded to even bytes.
array(int(0..1)) string2bits(string s)
Convert a Bittorrent style bitstring to an array of
int(0..1).
array(int) string2arr(string s)
Convert a Bittorrent style bitstring to an array of indices.
| Module Protocols.Bittorrent.PeerID |
string identify_peer(string peerid)
Decodes the given peerid , returning an identification string for the client software. Assumes the peerid string is exactly 20 characters long.
| Module Protocols.LDAP |
constant Protocols.LDAP.LDAP_SUCCESS
constant Protocols.LDAP.LDAP_OPERATIONS_ERROR
constant Protocols.LDAP.LDAP_PROTOCOL_ERROR
constant Protocols.LDAP.LDAP_TIMELIMIT_EXCEEDED
constant Protocols.LDAP.LDAP_SIZELIMIT_EXCEEDED
constant Protocols.LDAP.LDAP_COMPARE_FALSE
constant Protocols.LDAP.LDAP_COMPARE_TRUE
constant Protocols.LDAP.LDAP_AUTH_METHOD_NOT_SUPPORTED
constant Protocols.LDAP.LDAP_STRONG_AUTH_NOT_SUPPORTED
constant Protocols.LDAP.LDAP_STRONG_AUTH_REQUIRED
constant Protocols.LDAP.LDAP_PARTIAL_RESULTS
constant Protocols.LDAP.LDAP_REFERRAL
constant Protocols.LDAP.LDAP_ADMINLIMIT_EXCEEDED
constant Protocols.LDAP.LDAP_UNAVAILABLE_CRITICAL_EXTENSION
constant Protocols.LDAP.LDAP_CONFIDENTIALITY_REQUIRED
constant Protocols.LDAP.LDAP_SASL_BIND_IN_PROGRESS
constant Protocols.LDAP.LDAP_NO_SUCH_ATTRIBUTE
constant Protocols.LDAP.LDAP_UNDEFINED_TYPE
constant Protocols.LDAP.LDAP_INAPPROPRIATE_MATCHING
constant Protocols.LDAP.LDAP_CONSTRAINT_VIOLATION
constant Protocols.LDAP.LDAP_TYPE_OR_VALUE_EXISTS
constant Protocols.LDAP.LDAP_INVALID_SYNTAX
constant Protocols.LDAP.LDAP_NO_SUCH_OBJECT
constant Protocols.LDAP.LDAP_ALIAS_PROBLEM
constant Protocols.LDAP.LDAP_INVALID_DN_SYNTAX
constant Protocols.LDAP.LDAP_IS_LEAF
constant Protocols.LDAP.LDAP_ALIAS_DEREF_PROBLEM
constant Protocols.LDAP.LDAP_INAPPROPRIATE_AUTH
constant Protocols.LDAP.LDAP_INVALID_CREDENTIALS
constant Protocols.LDAP.LDAP_INSUFFICIENT_ACCESS
constant Protocols.LDAP.LDAP_BUSY
constant Protocols.LDAP.LDAP_UNAVAILABLE
constant Protocols.LDAP.LDAP_UNWILLING_TO_PERFORM
constant Protocols.LDAP.LDAP_LOOP_DETECT
constant Protocols.LDAP.LDAP_SORT_CONTROL_MISSING
constant Protocols.LDAP.LDAP_NAMING_VIOLATION
constant Protocols.LDAP.LDAP_OBJECT_CLASS_VIOLATION
constant Protocols.LDAP.LDAP_NOT_ALLOWED_ON_NONLEAF
constant Protocols.LDAP.LDAP_NOT_ALLOWED_ON_RDN
constant Protocols.LDAP.LDAP_ALREADY_EXISTS
constant Protocols.LDAP.LDAP_NO_OBJECT_CLASS_MODS
constant Protocols.LDAP.LDAP_RESULTS_TOO_LARGE
constant Protocols.LDAP.LDAP_AFFECTS_MULTIPLE_DSAS
constant Protocols.LDAP.LDAP_OTHER
constant Protocols.LDAP.LDAP_SERVER_DOWN
constant Protocols.LDAP.LDAP_LOCAL_ERROR
constant Protocols.LDAP.LDAP_ENCODING_ERROR
constant Protocols.LDAP.LDAP_DECODING_ERROR
constant Protocols.LDAP.LDAP_TIMEOUT
constant Protocols.LDAP.LDAP_AUTH_UNKNOWN
constant Protocols.LDAP.LDAP_FILTER_ERROR
constant Protocols.LDAP.LDAP_USER_CANCELLED
constant Protocols.LDAP.LDAP_PARAM_ERROR
constant Protocols.LDAP.LDAP_NO_MEMORY
constant Protocols.LDAP.LDAP_CONNECT_ERROR
constant Protocols.LDAP.LDAP_NOT_SUPPORTED
constant Protocols.LDAP.LDAP_CONTROL_NOT_FOUND
constant Protocols.LDAP.LDAP_NO_RESULTS_RETURNED
constant Protocols.LDAP.LDAP_MORE_RESULTS_TO_RETURN
constant Protocols.LDAP.LDAP_CLIENT_LOOP
constant Protocols.LDAP.LDAP_REFERRAL_LIMIT_EXCEEDED
LDAP result codes.
Protocols.LDAP.client.error_number , Protocols.LDAP.client.result.error_number
constant Protocols.LDAP.ldap_error_strings
Mapping from LDAP_* result codes to descriptive strings.
constant Protocols.LDAP.SEARCH_LOWER_ATTRS
constant Protocols.LDAP.SEARCH_MULTIVAL_ARRAYS_ONLY
constant Protocols.LDAP.SEARCH_RETURN_DECODE_ERRORS
Bitfield flags given to Protocols.LDAP.client.search :
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.
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.
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 Locale.Charset.DecodeError object.
constant Protocols.LDAP.SCOPE_BASE
constant Protocols.LDAP.SCOPE_ONE
constant Protocols.LDAP.SCOPE_SUB
Constants for the search scope used with e.g. Protocols.LDAP.client.set_scope .
Return the object specified by the DN.
Return the immediate subobjects of the object specified by the DN.
Return the object specified by the DN and all objects below it (on any level).
constant Protocols.LDAP.MODIFY_ADD
constant Protocols.LDAP.MODIFY_DELETE
constant Protocols.LDAP.MODIFY_REPLACE
Constants used in the attropval argument to
Protocols.LDAP.client.modify .
string ldap_encode_string(string str)
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.
ldap_decode_string , Protocols.LDAP.client.search
string ldap_decode_string(string str)
Decodes all \xx escapes in str .
ldap_encode_string
string encode_dn_value(string str)
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.
string canonicalize_dn(string dn, void|int strict)
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.
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.
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.
constant Protocols.LDAP.LDAP_CONTROL_MANAGE_DSA_IT
LDAP control: Manage DSA IT LDAPv3 control (RFC 3296): Control to indicate that the operation is intended to manage objects within the DSA (server) Information Tree.
constant Protocols.LDAP.LDAP_CONTROL_VLVREQUEST
LDAP control: LDAP Extensions for Scrolling View Browsing of Search Results (internet draft): Control used to request virtual list view support from the server.
constant Protocols.LDAP.LDAP_CONTROL_VLVRESPONSE
LDAP control: LDAP Extensions for Scrolling View Browsing of Search Results (internet draft): Control used to pass virtual list view (VLV) data from the server to the client.
constant Protocols.LDAP.LDAP_PAGED_RESULT_OID_STRING
LDAP control: Microsoft AD: Control to instruct the server to return the results of a search request in smaller, more manageable packets rather than in one large block.
constant Protocols.LDAP.LDAP_SERVER_ASQ_OID
LDAP control: Microsoft AD: Control to force the query to be based on a specific DN-valued attribute.
constant Protocols.LDAP.LDAP_SERVER_CROSSDOM_MOVE_TARGET_OID
LDAP control: Microsoft AD: Control used with an extended LDAP rename function to move an LDAP object from one domain to another.
constant Protocols.LDAP.LDAP_SERVER_DIRSYNC_OID
LDAP control: Microsoft AD: Control that enables an application to search the directory for objects changed from a previous state.
constant Protocols.LDAP.LDAP_SERVER_DOMAIN_SCOPE_OID
LDAP control: Microsoft AD: Control used to instruct the LDAP server not to generate any referrals when completing a request.
constant Protocols.LDAP.LDAP_SERVER_EXTENDED_DN_OID
LDAP control: Microsoft AD: Control to request an extended form of an Active Directory object distinguished name.
constant Protocols.LDAP.LDAP_SERVER_LAZY_COMMIT_OID
LDAP control: Microsoft AD: Control used to instruct the server to return the results of a DS modification command, such as add, delete, or replace, after it has been completed in memory, but before it has been committed to disk.
constant Protocols.LDAP.LDAP_SERVER_NOTIFICATION_OID
LDAP control: Microsoft AD: Control used with an extended LDAP asynchronous search function to register the client to be notified when changes are made to an object in Active Directory.
constant Protocols.LDAP.LDAP_SERVER_PERMISSIVE_MODIFY_OID
LDAP control: Microsoft AD: An LDAP modify request will normally fail if it attempts to add an attribute that already exists, or if it attempts to delete an attribute that does not exist. With this control, as long as the attribute to be added has the same value as the existing attribute, then the modify will succeed. With this control, deletion of an attribute that does not exist will also succeed.
constant Protocols.LDAP.LDAP_SERVER_QUOTA_CONTROL_OID
LDAP control: Microsoft AD: Control used to pass the SID of a security principal, whose quota is being queried, to the server in a LDAP search operation.
constant Protocols.LDAP.LDAP_SERVER_RESP_SORT_OID
LDAP control: Microsoft AD: Control used by the server to indicate the results of a search function initiated using the LDAP_SERVER_SORT_OID control.
constant Protocols.LDAP.LDAP_SERVER_SD_FLAGS_OID
LDAP control: Microsoft AD: Control used to pass flags to the server to control various security descriptor results.
constant Protocols.LDAP.LDAP_SERVER_SEARCH_OPTIONS_OID
LDAP control: Microsoft AD: Control used to pass flags to the server to control various search behaviors.
constant Protocols.LDAP.LDAP_SERVER_SHOW_DELETED_OID
LDAP control: Microsoft AD: Control used to specify that the search results include any deleted objects that match the search filter.
constant Protocols.LDAP.LDAP_SERVER_SORT_OID
LDAP control: Microsoft AD: Control used to instruct the server to sort the search results before returning them to the client application.
constant Protocols.LDAP.LDAP_SERVER_TREE_DELETE_OID
LDAP control: Microsoft AD: Control used to delete an entire subtree in the directory.
constant Protocols.LDAP.LDAP_SERVER_VERIFY_NAME_OID
LDAP control: Microsoft AD: Control used to instruct the DC accepting the update which DC it should verify with, the existence of any DN attribute values.
constant Protocols.LDAP.SYNTAX_ATTR_TYPE_DESCR
constant Protocols.LDAP.SYNTAX_BINARY
constant Protocols.LDAP.SYNTAX_BIT_STRING
constant Protocols.LDAP.SYNTAX_BOOLEAN
constant Protocols.LDAP.SYNTAX_CERT
constant Protocols.LDAP.SYNTAX_CERT_LIST
constant Protocols.LDAP.SYNTAX_CERT_PAIR
constant Protocols.LDAP.SYNTAX_COUNTRY_STR
constant Protocols.LDAP.SYNTAX_DN
constant Protocols.LDAP.SYNTAX_DIRECTORY_STR
constant Protocols.LDAP.SYNTAX_DIT_CONTENT_RULE_DESCR
constant Protocols.LDAP.SYNTAX_FACSIMILE_PHONE_NUM
constant Protocols.LDAP.SYNTAX_FAX
constant Protocols.LDAP.SYNTAX_GENERALIZED_TIME
constant Protocols.LDAP.SYNTAX_IA5_STR
constant Protocols.LDAP.SYNTAX_INT
constant Protocols.LDAP.SYNTAX_JPEG
constant Protocols.LDAP.SYNTAX_MATCHING_RULE_DESCR
constant Protocols.LDAP.SYNTAX_MATCHING_RULE_USE_DESCR
constant Protocols.LDAP.SYNTAX_MHS_OR_ADDR
constant Protocols.LDAP.SYNTAX_NAME_AND_OPTIONAL_UID
constant Protocols.LDAP.SYNTAX_NAME_FORM_DESCR
constant Protocols.LDAP.SYNTAX_NUMERIC_STRING
constant Protocols.LDAP.SYNTAX_OBJECT_CLASS_DESCR
constant Protocols.LDAP.SYNTAX_OID
constant Protocols.LDAP.SYNTAX_OTHER_MAILBOX
constant Protocols.LDAP.SYNTAX_POSTAL_ADDR
constant Protocols.LDAP.SYNTAX_PRESENTATION_ADDR
constant Protocols.LDAP.SYNTAX_PRINTABLE_STR
constant Protocols.LDAP.SYNTAX_PHONE_NUM
constant Protocols.LDAP.SYNTAX_UTC_TIME
constant Protocols.LDAP.SYNTAX_LDAP_SYNTAX_DESCR
constant Protocols.LDAP.SYNTAX_DIT_STRUCTURE_RULE_DESCR
LDAP syntax: Standard syntaxes from RFC 2252.
constant Protocols.LDAP.SYNTAX_CASE_EXACT_STR
"caseExactString" is an alias used in e.g. RFC 2079.
constant Protocols.LDAP.SYNTAX_DELIVERY_METHOD
constant Protocols.LDAP.SYNTAX_ENHANCED_GUIDE
constant Protocols.LDAP.SYNTAX_GUIDE
constant Protocols.LDAP.SYNTAX_OCTET_STR
constant Protocols.LDAP.SYNTAX_TELETEX_TERMINAL_ID
constant Protocols.LDAP.SYNTAX_TELETEX_NUM
constant Protocols.LDAP.SYNTAX_SUPPORTED_ALGORITHM
LDAP syntax: Standard syntaxes from RFC 2256.
constant Protocols.LDAP.SYNTAX_AD_CASE_IGNORE_STR
constant Protocols.LDAP.SYNTAX_AD_LARGE_INT
constant Protocols.LDAP.SYNTAX_AD_OBJECT_SECURITY_DESCRIPTOR
LDAP syntax: Microsoft AD: Additional syntaxes used in AD. C.f. <http://community.roxen.com/(all)/developers/idocs/drafts/ draft-armijo-ldap-syntax-00.html>.
constant Protocols.LDAP.mapping
Mapping containing functions to decode charsets in syntaxes where that's necessary. If the syntax is complex in a way that makes the result ambiguous if decoded with a single charset transformation then it should typically not be decoded here.
These decoders are used on all attribute values returned by Protocols.LDAP.client.result functions.
constant Protocols.LDAP.mapping
Mapping containing the reverse functions from syntax_decode_fns .
constant Protocols.LDAP.GUID_USERS_CONTAINER
constant Protocols.LDAP.GUID_COMPUTERS_CONTAI