12. Protocols

  Module Protocols.HTTP


Method filename_to_type
Method extension_to_type

string Protocols.HTTP.filename_to_type(string filename)
string Protocols.HTTP.extension_to_type(string extension)

Description

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


Method http_date

string Protocols.HTTP.http_date(int time)

Description

Makes a time notification suitable for the HTTP protocol. @param time The time in seconds since the 00:00:00 UTC, January 1, 1970 @returns The date in the HTTP standard date format. Example : Thu, 03 Aug 2000 05:40:39 GMT


Method http_decode_string
Method http_decode_urlencoded_query

string Protocols.HTTP.http_decode_string(string what)
mapping(string:string|array(string)) Protocols.HTTP.http_decode_urlencoded_query(string query, void|mapping dest)

Description

Decodes an URL-encoded query into a mapping.


Method get_url

Protocols.HTTP.Query Protocols.HTTP.get_url(string|Standards.URI url)
Protocols.HTTP.Query Protocols.HTTP.get_url(string|Standards.URI url, mapping query_variables)
Protocols.HTTP.Query Protocols.HTTP.get_url(string|Standards.URI url, mapping query_variables, mapping request_headers)
Protocols.HTTP.Query Protocols.HTTP.get_url(string|Standards.URI url, mapping query_variables, mapping request_headers, Protocols.HTTP.Query query)

Description

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


Method put_url

Protocols.HTTP.Query Protocols.HTTP.put_url(string|Standards.URI url)
Protocols.HTTP.Query Protocols.HTTP.put_url(string|Standards.URI url, string file)
Protocols.HTTP.Query Protocols.HTTP.put_url(string|Standards.URI url, string file, mapping query_variables)
Protocols.HTTP.Query Protocols.HTTP.put_url(string|Standards.URI url, string file, mapping query_variables, mapping request_headers)
Protocols.HTTP.Query Protocols.HTTP.put_url(string|Standards.URI url, string file, mapping query_variables, mapping request_headers, Protocols.HTTP.Query query)

Description

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


Method delete_url

Protocols.HTTP.Query Protocols.HTTP.delete_url(string|Standards.URI url)
Protocols.HTTP.Query Protocols.HTTP.delete_url(string|Standards.URI url, mapping query_variables)
Protocols.HTTP.Query Protocols.HTTP.delete_url(string|Standards.URI url, mapping query_variables, mapping request_headers)
Protocols.HTTP.Query Protocols.HTTP.delete_url(string|Standards.URI url, mapping query_variables, mapping request_headers, Protocols.HTTP.Query query)

Description

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


Method get_url_nice
Method get_url_data

array(string) Protocols.HTTP.get_url_nice(string|Standards.URI url, mapping query_variables)
array(string) Protocols.HTTP.get_url_nice(string|Standards.URI url, mapping query_variables, mapping request_headers)
array(string) Protocols.HTTP.get_url_nice(string|Standards.URI url, mapping query_variables, mapping request_headers, Protocols.HTTP.Query query)
string Protocols.HTTP.get_url_data(string|Standards.URI url, mapping query_variables)
string Protocols.HTTP.get_url_data(string|Standards.URI url, mapping query_variables, mapping request_headers)
string Protocols.HTTP.get_url_data(string|Standards.URI url, mapping query_variables, mapping request_headers, Protocols.HTTP.Query query)

Description

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


Method post_url_nice
Method post_url_data
Method post_url

array(string) Protocols.HTTP.post_url_nice(string|Standards.URI url, mapping query_variables)
array(string) Protocols.HTTP.post_url_nice(string|Standards.URI url, mapping query_variables, mapping request_headers)
array(string) Protocols.HTTP.post_url_nice(string|Standards.URI url, mapping query_variables, mapping request_headers, Protocols.HTTP.Query query)
string Protocols.HTTP.post_url_data(string|Standards.URI url, mapping query_variables)
string Protocols.HTTP.post_url_data(string|Standards.URI url, mapping query_variables, mapping request_headers)
string Protocols.HTTP.post_url_data(string|Standards.URI url, mapping query_variables, mapping request_headers, Protocols.HTTP.Query query)
Protocols.HTTP.Query Protocols.HTTP.post_url(string|Standards.URI url, mapping query_variables)
Protocols.HTTP.Query Protocols.HTTP.post_url(string|Standards.URI url, mapping query_variables, mapping request_headers)
Protocols.HTTP.Query Protocols.HTTP.post_url(string|Standards.URI url, mapping query_variables, mapping request_headers, Protocols.HTTP.Query query)

Description

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


Method unentity

string Protocols.HTTP.unentity(string s)

Description

Helper function for replacing HTML entities with the corresponding iso-8859-1 characters.

Note

All characters aren't replaced, only those with corresponding iso-8859-1 characters.


Method http_encode_query

string Protocols.HTTP.http_encode_query(mapping(string:int|string) variables)

Description

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

Example:

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


Method http_encode_string

string Protocols.HTTP.http_encode_string(string in)

Description

This protects all odd - see http_encode_query() - characters for transfer in HTTP.

Do not use this function to protect URLs, since it will protect URL characters like '/' and '?'.

Parameter in

The string to encode

Returns

The HTTP encoded string


Method http_encode_cookie

string Protocols.HTTP.http_encode_cookie(string f)

Description

Encode the specified string in as to the HTTP cookie standard.

Parameter f

The string to encode.

Returns

The HTTP cookie encoded string.

  CLASS Protocols.HTTP.HeaderParser

Description

Fast HTTP header parser.

  CLASS Protocols.HTTP.Query

Description

Open and execute an HTTP query.


Variable errno

int errno

Description

Errno copied from the connection.


Variable ok

int ok

Description

Tells if the connection is successfull.


Variable headers

mapping headers

Description

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


Variable protocol

string protocol

Description

Protocol string, ie "HTTP/1.0".


int status
string status_desc

Description

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


Variable hostname_cache

mapping hostname_cache

Description

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


Method set_callbacks
Method async_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)

Description

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

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

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

Returns

Returns the called object


Method thread_request

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

Description

Create a new query object and begin the query.

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

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

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

Returns

Returns the called object.


Method `()

int `()()

Description

Wait for connection to complete.

Returns

Returns 1 on successfull connection, 0 on failure.


Method data

string data(int|void max_length)

Description

Gives back the data as a string.


Method downloaded_bytes

int downloaded_bytes()

Description

Gives back the number of downloaded bytes.


Method total_bytes

int total_bytes()

Description

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


Method cast

array cast("array")

Description

Gives back

({mapping headers, string data,
		           string protocol, int status, string status_desc});


Method cast

mapping cast("mapping")

Description

Gives back

 headers |
	(["protocol":protocol,
	  "status":status number,
	  "status_desc":status description,
	  "data":data]); 


Method cast

string cast("string")

Description

Gives back the answer as a string.


Method file

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

Description

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

newheaders , removeheaders is applied as:

(oldheaders|newheaders))-removeheaders
Make sure all new and remove-header indices are lower case.

See also

datafile()


Method datafile

Protocols.HTTP.Query.PseudoFile datafile()

Description

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

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

See also

file()


Method async_fetch

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

Description

Fetch all data in background.

  Module Protocols.HTTP.Server

  CLASS Protocols.HTTP.Server.Port

Description

The simplest server possible. Binds a port and calls a callback with Server.Request objects.


Method create
Method close

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

Description

Closes the HTTP port.

  CLASS Protocols.HTTP.Server.Request


Variable raw

string raw

Description

raw unparsed full request (headers and body)


Variable body_raw

string body_raw

Description

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


Variable request_raw

string request_raw

Description

full request line (request_type + full_query + protocol )


Variable request_type

string request_type

Description

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


Variable full_query

string full_query

Description

full resource requested, including attached GET query


Variable not_query

string not_query

Description

resource requested minus any attached query


Variable query

string query

Description

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


Variable protocol

string protocol

Description

request protocol and version, eg. HTTP/1.0


Variable request_headers

mapping(string:string|array(string)) request_headers

Description

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


Variable variables

mapping(string:string|array(string)) variables

Description

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


Variable cookies

mapping(string:string) cookies

Description

cookies set by client


Variable misc

mapping misc

Description

external use only


Method response_and_finish

void response_and_finish(mapping m, function|void _log_cb)

Description

return a properly formatted response to the HTTP client

Parameter m

Contains elements for generating a response to the client.

"data" : string

Data to be returned to the client.

"file" : object

File object, the contents of which will be returned to the client.

"error" : int

HTTP error code

"length" : int

length of content returned. If file is provided, size bytes will be returned to client.

"modified" : string

contains optional modification date.

"type" : string

contains optional content-type

"extra_heads" : mapping

contains a mapping of additional headers to be returned to client.

"server" : string

contains the server identification header.


  CLASS Protocols.HTTP.Server.SSLPort

Description

The simplest SSL server possible. Binds a port and calls a callback with Request objects.


Method create

void Protocols.HTTP.Server.SSLPort(function(Request:void) _callback, void|int _portno, void|string _interface, void|string key, void|string certificate)

Description

Create a HTTPS (HTTP over SSL) server.

Parameter _callback

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

Parameter _portno

The port number to bind to, defaults to 443.

Parameter _interface

The interface address to bind to.

Parameter key

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

Parameter certificate

An optional SSL certificate, provided in binary format.


Method close

void close()

Description

Closes the HTTP port.


Method new_connection

void new_connection()

Description

The port accept callback

  CLASS Protocols.HTTP.Server.SSLPort.MySSLPort


Inherit sslport

inherit SSL.sslport : sslport


Method set_default_keycert

void set_default_keycert()


Method set_key

void set_key(string skey)


Method set_certificate

void set_certificate(string certificate)

  Module SSL

  CLASS SSL.alert

Description

Alert package.


Inherit packet

inherit "packet" : packet


Method create

void SSL.alert(int level, int description, string|void message, mixed|void trace)

  CLASS SSL.cipher

Description

Encryption and MAC algorithms used in SSL.


Inherit "constants"

inherit "constants"

  CLASS SSL.connection

Description

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

inherit "constants"


Inherit "handshake"

inherit "handshake"


Inherit alert

inherit Queue : alert


Inherit urgent

inherit Queue : urgent


Inherit application

inherit Queue : application


Method set_alert_callback

void set_alert_callback(function(object:void) callback)

Description

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

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


Method recv_packet

object recv_packet(string data)

Description

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


Method send_packet

void send_packet(object packet, int|void priority)

Description

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


Method to_write

string|int to_write()

Description

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

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


Method send_close

void send_close()

Description

Initiate close.


Method got_data

string|int got_data(string|int s)

Description

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

Description

Protocol constants

  CLASS SSL.context

Description

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.


Inherit "constants"

inherit "constants"


Variable rsa

object rsa

Description

The server's private key


object long_rsa
object short_rsa

Description

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.


Variable random

function(int:string) random

Description

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


Variable certificates

array(string) certificates

Description

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


Variable preferred_auth_methods

array(int) preferred_auth_methods

Description

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


Variable preferred_suites

array(int) preferred_suites

Description

Cipher suites we want the server to support, best first.


Variable preferred_compressors

array(int) preferred_compressors

Description

Always ({ COMPRESSION_null })


Variable use_cache

int use_cache

Description

Non-zero to enable cahing of sessions


Variable session_lifetime

int session_lifetime

Description

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


Method lookup_session

object lookup_session(string id)

Description

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


Method new_session

object new_session()

Description

Create a new session.


Method record_session

void record_session(object s)

Description

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


Method purge_session

void purge_session(object s)

Description

Remove a session from the cache.

  CLASS SSL.handshake

Description

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.


Inherit "cipher"

inherit "cipher"


Variable auth_level

int auth_level

Description

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


Variable authorities

array(string) authorities

Description

Array of authorities that are accepted for client certificates. The client will only send certificates that are signed by any of these authorities. The string is the DER-encoded issuer.


string client_random
string server_random

Description

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


Method handle_handshake

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

Description

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

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

  CLASS SSL.https

Description

Dummy HTTPS server


Inherit "sslport"

inherit "sslport"

  CLASS SSL.packet

Description

SSL Record Layer. Handle formatting and parsing of packets.


Inherit "constants"

inherit "constants"

  CLASS SSL.session

Description

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

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


Inherit cipher

inherit "cipher" : cipher


Variable identity

string identity

Description

Identifies the session to the server


Variable compression_algorithm

int compression_algorithm

Description

Always COMPRESSION_null.


Variable cipher_suite

int cipher_suite

Description

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


Variable cipher_spec

object cipher_spec

Description

Information about the encryption method derived from the cipher_suite.


Variable ke_method

int ke_method

Description

Key exchange method, also derived from the cipher_suite.


Variable master_secret

string master_secret

Description

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


Method set_cipher_suite

void set_cipher_suite(int suite, int version)


Method set_compression_method

void set_compression_method(int compr)


Method new_server_states

array new_server_states(string client_random, string server_random, array(int) version)

Description

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

Returns
Array
State read_state

Read state

State write_state

Write state



Method new_client_states

array new_client_states(string client_random, string server_random, array(int) version)

Description

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

Returns
Array
State read_state

Read state

State write_state

Write state


  CLASS SSL.sslfile

Description

Interface similar to Stdio.File.


Inherit connection

inherit "connection" : connection

  CLASS SSL.sslport

Description

Interface similar to Stdio.Port.


Inherit socket

inherit Stdio.Port : socket


Inherit "context"

inherit "context"


Inherit accept_queue

inherit ADT.Queue : accept_queue

  CLASS SSL.state

Description

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.


Inherit "constants"

inherit "constants"


Variable session

object session

Description

Information about the used algorithms.


Variable mac

object mac

Description

Message Authentication Code


Variable crypt

object crypt

Description

Encryption or decryption object.


Variable seq_num

Gmp.mpz|int seq_num

Description

64-bit sequence number.


Method decrypt_packet

object decrypt_packet(object packet, int version)

Description

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


Method encrypt_packet

object encrypt_packet(object packet, int version)

Description

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

  Module Protocols.LysKOM

  CLASS Protocols.LysKOM.Connection

Description

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


Method XXX
Method async_XXX
Method async_cb_XXX

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

Description

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

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

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


int protocol_level
string session_software
string software_version

Description

Description of the connected server.


Method create

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

Description

The options argument is a mapping with the following members:

"login" : int|string

login as this person number (get number from name).

"password" : string

send this login password.

"invisible" : int(0..1)

if set, login invisible.

"port" : int(0..65535)

server port (default is 4894).

"whoami" : string

present as this user (default is from uid/getpwent and hostname).


  CLASS Protocols.LysKOM.Session


Variable user

object user

Description

This variable contains the Protocols.LysKOM.Session.Person that is logged in.


Method create

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

Description

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

options is a mapping of options:

"login" : int|string

login as this person number (get number from name).

"create" : string

create a new person and login with it.

"password" : string

send this login password.

"invisible" : int(0..1)

if set, login invisible.

"port" : int(0..65535)

server port (default is 4894).

"whoami" : string

present as this user (default is from uid/getpwent and hostname).


See also

Connection


Method text

Text text(int no)

Description

Returns the text no .


Method person

Person person(int no)

Description

Returns the person no .


Method conference

Conference conference(int no)

Description

Returns conference number no .


Method try_complete_person

array(ProtocolTypes.ConfZInfo) try_complete_person(string orig)

Description

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


Method login

object login(int user_no, string password)
object login(int user_no, string password, int invisible)

Description

Performs a login. Throws a lyskom error if unsuccessful.

Returns

The session object logged in.


Method create_person

object create_person(string name, string password)

Description

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


Method logout

object logout()

Description

Logouts from the server. returns the called object


Method create_text

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

Description

Creates a new text.

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

options is a mapping that may contain:

"recpt" : Conference|array(Conference)

recipient conferences.

"cc" : Conference|array(Conference)

cc-recipient conferences.

"bcc" : Conference|array(Conference)

bcc-recipient conferences*.

"comm_to" : Text|array(Text)

The text(s) to be commented.

"foot_to" : Text|array(Text)

The text(s) to be footnoted.

"anonymous" : int(0..1)

send text anonymously.

"aux_items" : array(AuxItemInput)

AuxItems you want to set for the text*.


Note

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

See also

Conference.create_text() , Text.comment() , Text.footnote()


Method send_message

object|void send_message(string textstring, mapping options)

Description

Sends a message.

options is a mapping that may contain:

"recpt" : Conference

recipient conference.



Method register_async_message_callback

void register_async_message_callback(function(int:void) cb)

  CLASS Protocols.LysKOM.Session.AuxItemInput

FIXME

Undocumented


Inherit AuxItemInput

inherit ProtocolTypes.AuxItemInput : AuxItemInput

  CLASS Protocols.LysKOM.Session.AuxItems

FIXME

Undocumented

  CLASS Protocols.LysKOM.Session.Text

Description

All variables in this class is read only.

FIXME

Undocumented


Variable no

int no

Description

The text number, as spicified to create .


Variable err

object err

Description

Undocumented


Method create

void Protocols.LysKOM.Session.Text(string textnumber)

Description

Initializes a Text object.


Method mark_as_read

void mark_as_read()

FIXME

Undocumented.


mixed prefetch_text
mixed prefetch_stat
mixed lines
mixed characters
mixed clear_stat
mixed aux_items

FIXME

Undocumented


Variable text

string text

Description

The actual text (or body if you wish).


Variable subject

string subject

Description

The message subject.


Variable author

string author

Description

The author of the text.


Variable misc

mixed misc

Description

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

FIXME

Needs a more complete description.


Variable marks

int marks

Description

The number of marks on this text.


Variable creation_time

mixed creation_time

Description

The time the text was created on the server.

  CLASS Protocols.LysKOM.Session.Membership

Description

All variables in this class is read only.


Variable last_time_read

object last_time_read


Variable priority

int(0..255) priority


Variable last_text_read

int last_text_read


Variable read_texts

array(int) read_texts


Variable added_at

object added_at


Variable type

multiset(string) type


Variable position

int position


Variable conf

object conf


Method number_unread

int number_unread()


Method query_read_texts

void query_read_texts()


Method unread_texts

array(object) unread_texts()

  CLASS Protocols.LysKOM.Session.Person


Variable no

int no


Method create

void Protocols.LysKOM.Session.Person(int no)


mixed prefetch_stat
mixed prefetch_conf
mixed prefetch_membership

FIXME

Undocumented


object error
Text user_area
mixed username
mixed privileges
mixed flags
mixed last_login
mixed total_time_present
mixed sessions
mixed created_lines
mixed created_bytes
mixed read_texts
mixed no_of_text_fetches
mixed created_persons
mixed created_confs
mixed first_created_local_no
mixed no_of_created_texts
mixed no_of_marks
mixed no_of_confs
mixed unread
int(0..0) clear_membership
mixed membership

FIXME

Undocumented

  CLASS Protocols.LysKOM.Session.Conference


Method create

void Protocols.LysKOM.Session.Conference(int no)

  Module Protocols.LysKOM.Request

Description

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

  CLASS Protocols.LysKOM.Request._Request

Description

This is the main request class. All lyskom request classes inherit this class.


Method async
Method sync

void async(mixed ... args)
mixed sync(mixed ... args)

Description

Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. This calls indata() in itself, to get the correct arguments to the lyskom protocol call.


Method _async
Method _sync

void _async(int call, mixed_data)
mixed _sync(int call, mixed_data)

Description

Initialise an asynchronous or a synchronous call, the latter is also evaluating the result. These are called by async and sync respectively.


Method _reply
Method reply

mixed _reply(object|array what)
mixed reply(object|array what)

Description

_reply() is called as callback to evaluate the result, and calls reply() in itself to do the real work.


Method `()

mixed `()()

Description

Wait for the call to finish.


Variable ok

int(0..1) ok

Description

Tells if the call has executed ok


Variable error

object error

Description

How the call failed. The call has completed if

(ok||error)
.

  Module Protocols.DNS

Description

Domain Name System RFC 1035


Constant C_IN

constant Protocols.DNS.C_IN

Description

Class Internet


Constant C_CH

constant Protocols.DNS.C_CH

Description

Class CHAOS


Constant C_HS

constant Protocols.DNS.C_HS

Description

Class Hesiod


Constant C_ANY

constant Protocols.DNS.C_ANY

Description

Class ANY


Constant T_A

constant Protocols.DNS.T_A

Description

Type - host address


Constant T_NS

constant Protocols.DNS.T_NS

Description

Type - authoritative name server


Constant T_MD

constant Protocols.DNS.T_MD

Description

Type - mail destination (Obsolete - use MX)


Constant T_MF

constant Protocols.DNS.T_MF

Description

Type - mail forwarder (Obsolete - use MX)


Constant T_CNAME

constant Protocols.DNS.T_CNAME

Description

Type - canonical name for an alias


Constant T_SOA

constant Protocols.DNS.T_SOA

Description

Type - start of a zone of authority


Constant T_MB

constant Protocols.DNS.T_MB

Description

Type - mailbox domain name (EXPERIMENTAL)


Constant T_MG

constant Protocols.DNS.T_MG

Description

Type - mail group member (EXPERIMENTAL)


Constant T_MR

constant Protocols.DNS.T_MR

Description

Type - mail rename domain name (EXPERIMENTAL)


Constant T_NULL

constant Protocols.DNS.T_NULL

Description

Type - null RR (EXPERIMENTAL)


Constant T_WKS

constant Protocols.DNS.T_WKS

Description

Type - well known service description


Constant T_PTR

constant Protocols.DNS.T_PTR

Description

Type - domain name pointer


Constant T_HINFO

constant Protocols.DNS.T_HINFO

Description

Type - host information


Constant T_MINFO

constant Protocols.DNS.T_MINFO

Description

Type - mailbox or mail list information


Constant T_MX

constant Protocols.DNS.T_MX

Description

Type - mail exchange


Constant T_TXT

constant Protocols.DNS.T_TXT

Description

Type - text strings


Constant T_AAAA

constant Protocols.DNS.T_AAAA

Description

Type - IPv6 address record (RFC 1886, deprecated)


Constant T_SRV

constant Protocols.DNS.T_SRV

Description

Type - Service location record (RFC 2782)


Constant T_A6

constant Protocols.DNS.T_A6

Description

Type - IPv6 address record (RFC 2874, incomplete support)

  CLASS Protocols.DNS.protocol

Description

Low level DNS protocol


Method mkquery

string mkquery(string|mapping dnameorquery, int|void cl, int|void type)

Description

create a DNS query PDU

Parameter dnameorquery
Parameter cl

record class such as Protocols.DNS.C_IN

Parameter type

query type such Protocols.DNS.T_A

Returns

data suitable for use with Protocols.DNS.client.do_sync_query

Example

// generate a query PDU for a address lookup on the hostname pike.ida.liu.se string q=Protocols.DNS.protocol()->mkquery("pike.ida.liu.se", Protocols.DNS.C_IN, Protocols.DNS.T_A);

  CLASS Protocols.DNS.client

Description

Synchronous DNS client.


Inherit protocol

inherit protocol : protocol


Method create

void Protocols.DNS.client()
void Protocols.DNS.client(void|string|array server, void|int|array domain)


Method do_sync_query

mapping do_sync_query(string s)

Description

perform a syncronous query

Parameter s

result of Protocols.DNS.protocol.mkquery

Returns

mapping containing query result or 0 on failure/timeout

Example

// perform a hostname lookup, results stored in r->an object d=Protocols.DNS.client(); mapping r=d->do_sync_query(d->mkquery("pike.ida.liu.se", C_IN, T_A));


Method gethostbyname

array gethostbyname(string hostname)

Description

Queries the host name from the default or given DNS server. The result is an array with three elements,

Returns

An array with the requested information about the specified host.

Array
string hostname

Hostname.

array(string) ip

IP number(s).

array(string) aliases

DNS name(s).



Method getsrvbyname

array getsrvbyname(string service, string protocol, string|void name)

Description

Queries the service record (RFC 2782) from the default or given DNS server. The result is an array of arrays with the following six elements for each record. The array is sorted according to the priority of each record.

Each element of the array returned represents a service record. Each service record contains the following:

Returns

An array with the requested information about the specified service.

Array
int priority

Priority

int weight

Weight in event of multiple records with same priority.

int port

port number

string target

target dns name



Method gethostbyaddr

array gethostbyaddr(string hostip)

Description

Queries the host name or ip from the default or given DNS server. The result is an array with three elements,

Returns

The requested data about the specified host.

Array
string hostip

The host IP.

array(string) ip

IP number(s).

array(string) aliases

DNS name(s).



Method get_primary_mx

string get_primary_mx(string hostname)

Description

Queries the primary mx for the host.

Returns

Returns the hostname of the primary mail exchanger.

  Module Protocols

  Module Protocols.LDAP

  CLASS Protocols.LDAP.client

Description

Contains the client implementation of the LDAP protocol. All of the version 2 protocol features are implemented but only the base parts of the version 3.


Inherit protocol

inherit .protocol : protocol


Variable info

mapping info

Description

Several information about code itself and about active connection too


Method create

void Protocols.LDAP.client()
void Protocols.LDAP.client(string url)
void Protocols.LDAP.client(string url, object context)

Description

Create object. The first optional argument can be used later for subsequence operations. The second one can specify TLS context of connection. The default context only allows 128-bit encryption methods, so you may need to provide your own context if your LDAP server supports only export encryption.

Parameter url

LDAP server URL in form "ldap://hostname/basedn?attrlist?scope?ext"

Parameter context

TLS context of connection

See also

LDAP.client.bind , LDAP.client.search


Method bind

int bind()
int bind(string dn, string password)
int bind(string dn, string password, int version)

Description

Authenticates connection to the direcory.

First form uses default value previously entered in create.

Second form uses value from parameters:

Parameter dn

The distinguished name (DN) of an entry aginst which will be made authentication.

Parameter password

Password used for authentication.

Third form allows specify the version of LDAP protocol used by connection to the LDAP server.

Parameter version

Only 2 or 3 can be entered.

Returns

Returns 1 on success, 0 otherwise.

Note

Only simple authentication type is implemented. So be warned clear text passwords are sent to the directory server.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method unbind

int unbind()

Description

Unbinds from the directory and close the connection.


Method delete

int delete(string dn)

Description

Deletes entry from the LDAP server.

Parameter dn

The distinguished name of deleted entry.

Returns

Returns 1 on success, 0 otherwise.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method compare

int compare(string dn, array(string) aval)

Description

Compares given attribute value with one in the directory.

Parameter dn

The distinguished name of compared entry.

Parameter aval

The mapping of compared attributes and theirs values.

Returns

Returns 1 on success, 0 otherwise.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method add

int add(string dn, mapping(string:array(string)) attrs)

Description

The Add Operation allows a client to request the addition of an entry into the directory

Parameter dn

The Distinguished Name of the entry to be added.

Parameter attrs

The mapping of attributes and their values that make up the content of the entry being added.

Returns

Returns 1 on success, 0 otherwise.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method search

object|int search(string|void filter, array(string)|void attrs, int|void attrsonly)

Description

Search LDAP directory.

Parameter filter

Search filter used when searching directory objects.

Parameter attrs

The array of attribute names which will be returned by server. for every entry.

Parameter attrsonly

The flag causes server return only attribute name but not the attribute values.

Returns

Returns object LDAP.client.result on success, 0 otherwise.

Note

For syntax of search filter see at RFC 1960 (http://community.roxen.com/developers/idocs/rfc/rfc1960.html).

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.

See also

LDAP.client.result , LDAP.client.result.fetch


Method set_basedn

string set_basedn(string base_dn)

Parameter base_dn

base DN for search


Method set_scope

int set_scope(int|string scope)

Description

Sets value of scope for search operation.

Parameter scope

Value can be integer or its corresponding string value. 0: base, 1: one, 2: sub


Method set_option

int set_option(int opttype, int value)

Parameter option_type

LDAP_OPT_xxx

Parameter value

new value for option


Method get_option

int get_option(int opttype)

Parameter option_type

LDAP_OPT_xxx


Method modifydn

int modifydn(string dn, string newrdn, int deleteoldrdn, string|void newsuperior)

Description

The Modify DN Operation allows a client to change the leftmost (least significant) component of the name of an entry in the directory, or to move a subtree of entries to a new location in the directory.

Parameter dn

DN of source object

Parameter newrdn

RDN of destination

Parameter deleteoldrdn

The parameter controls whether the old RDN attribute values are to be retained as attributes of the entry, or deleted from the entry.

Parameter newsuperior

If present, this is the Distinguished Name of the entry which becomes the immediate superior of the existing entry.

Returns

Returns 1 on success, 0 otherwise.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method modify

int modify(string dn, mapping(string:array(mixed)) attropval)

Description

The Modify Operation allows a client to request that a modification of an entry be performed on its behalf by a server.

Parameter dn

The distinguished name of modified entry.

Parameter attropval

The mapping of attributes with requested operation and attribute's values.

attropval=([ attribute: ({operation, value1, value2, ...}) ])

where operation is one of the following: 0 (LDAP_OPERATION_ADD) - add values listed to the given attribute, creating the attribute if necessary 1 (LDAP_OPERATION_DELETE) - delete values listed from the given attribute, removing the entire attribute if no values are listed, or if all current values of the attribute are listed for deletion 2 (LDAP_OPERATION_REPLACE) - replace all existing values of the given attribute with the new values listed, creating the attribute if it did not already exist. A replace with no value will delete the entire attribute if it exists, and is ignored if the attribute does not exist

Returns

Returns 1 on uccess, 0 otherwise.

Note

The API change: the returning code was changed in Pike 7.3+ to follow his logic better.


Method get_referrals

array|int get_referrals()

Description

Gets referrals.

Returns

Returns array of referrals or 0.


Method parse_url

mapping|int parse_url(string ldapuri)

Parameter ldapuri

LDAP URL

  CLASS Protocols.LDAP.client.result

Description

Contains the result of a LDAP search.

See also

LDAP.client.search , LDAP.client.result.fetch


Method create

object|int Protocols.LDAP.client.result(array rawres, int|void stuff)

Description

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


Method error_number

int error_number()

Description

Returns error number of search result.

See also

LDAP.client.result.error_string


Method error_string

string error_string()

Description

Returns error description of search result.

See also

LDAP.client.result.error_number


Method num_entries

int num_entries()

Description

Returns the number of entries.

See also

LDAP.client.result.count_entries


Method count_entries

int count_entries()

Description

Returns the number of entries from current cursor possition till end of the list.

See also

LDAP.client.result.first , LDAP.client.result.next


Method fetch

int|mapping(string:array(string)) fetch(int|void idx)

Description

Returns a mapping with an entry for each attribute. Each entry is an array of values of the attribute.

Parameter index

Optional argument can be used for direct access to the entry other then currently pointed by cursor.


Method get_dn

string get_dn()

Description

Returns distinguished name (DN) of the current entry in the result list. Notice that this is the same as fetch()->dn[0].


Method first

void first()

Description

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

See also

LDAP.client.result.next


Method next

int next()

Description

Moves the result cursor to the next entry in the result list. Returns number of remained entries in the result list. Returns 0 at the end.

See also

LDAP.client.result.next

  CLASS Protocols.LDAP.protocol


Inherit ldap

inherit Stdio.File : ldap


Method error_number

int error_number()

Description

Returns error number of last transaction.

See also

LDAP.protocol.error_string


Method error_string

string error_string()

Description

Returns error description of search result.

See also

LDAP.protocol.error_number

  Module Protocols.SNMP

Description

SNMPv1 and v2c

  CLASS Protocols.SNMP.agent

Description

A simple SNMP agent with support for SNMP Get requests


Inherit "protocol"

inherit "protocol"


Method create

void Protocols.SNMP.agent(int|void port, string|void addr)

Description

create a new instance of the agent

Parameter port

the port number to listen for requests on

Parameter addr

the address to bind to for listening

Note

only one agent may be bound to a port at one time the agent does not currently support SMUX or AGENTX or other agent multiplexing protocols.


Method set_threaded

void set_threaded()

Description

Run the agent event loop in a thread, if available.


Method set_managers_only

void set_managers_only(int yesno)

Description

enable manager access limits

Parameter yesno

1 to allow only managers to submit requests 0 to allow any host to submit requests

default setting allows all requests from all hosts


Method set_get_communities

void set_get_communities(array communities)

Description

set the valid community strings for Get requests

Parameter communities

an array of valid Get communities

Note

send an empty array to disable Get requests


Method set_set_communities

void set_set_communities(array communities)

Description

set the valid community strings for Set requests

Parameter communities

an array of valid Set communities

Note

send an empty array to disable Set requests


Method set_managers

void set_managers(array managers)

Description

set the valid manager list for requests

Parameter managers

an array of valid management hosts

Note

send an empty array to disable all requests


Method set_set_oid_callback

void set_set_oid_callback(string oid, function cb)

Description

set the Set request callback function for an Object Identifier

Parameter oid

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to serve as the handler for all requests for which a handler is specified.

Parameter cb

the function to call when oid is requested by a manager the function should take 3 arguments: a string containing the requested oid, the desired value, and the body of the request as a mapping. The function should return an array containing 3 elements: The first is a boolean indicating success or failure. If success, the next 2 elements should be the SNMP data type of the result followed by the result itself. If failure, the next 2 elements should be the error-status such as Protocols.SNMP.ERROR_TOOBIG and the second is the error-index, if any.

Note

there can be only one callback per object identifier. calling this function more than once with the same oid will result in the new callback replacing the existing one.


Method clear_set_oid_callback

int clear_set_oid_callback(string oid)

Description

clear the Set callback function for an Object Identifier

Parameter oid

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler.

Returns

1 if the callback existed, 0 otherwise


Method get_set_oid_callback

void|function get_set_oid_callback(string oid)

Description

get the Set request callback function for an Object Identifier

Parameter oid

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler

Returns

the function associated with oid, if any


Method set_get_oid_callback

void set_get_oid_callback(string oid, function cb)

Description

set the Get request callback function for an Object Identifier

Parameter oid

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to serve as the handler for all requests for which a handler is specified.

Parameter cb

the function to call when oid is requested by a manager the function should take 2 arguments: a string containing the requested oid and the body of the request as a mapping. The function should return an array containing 3 elements: The first is a boolean indicating success or failure. If success, the next 2 elements should be the SNMP data type of the result followed by the result itself. If failure, the next 2 elements should be the error-status such as Protocols.SNMP.ERROR_TOOBIG and the second is the error-index, if any.

Note

there can be only one callback per object identifier. calling this function more than once with the same oid will result in the new callback replacing the existing one.


Method clear_get_oid_callback

int clear_get_oid_callback(string oid)

Description

clear the Get callback function for an Object Identifier

Parameter oid

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler.

Returns

1 if the callback existed, 0 otherwise


Method get_get_oid_callback

void|function get_get_oid_callback(string oid)

Description

get the Get request callback function for an Object Identifier

Parameter oid

the string object identifier, such as 1.3.6.1.4.1.132.2 or an asterisk (*) to indicate the default handler

Returns

the function associated with oid, if any

  CLASS Protocols.SNMP.protocol

Description

SNMP protocol implementation for Pike

RFCs:

implemented (yet): 1155-7 : v1

1901-4 : v2/community (Bulk ops aren't implemented!)

planned: 2742 : agentX

2570 : v3 description


Inherit snmp

inherit Stdio.UDP : snmp


Variable snmp_version

int snmp_version

Description

SNMP version

currently version 1 and 2 are supported.


Variable snmp_community

string snmp_community

Description

SNMP community string

should be set to the appropriate SNMP community before sending a request.

Note

Set to "public" by default.


Method create

void Protocols.SNMP.protocol(int|void rem_port, string|void rem_addr, int|void loc_port, string|void loc_addr)

Description

create a new SNMP protocol object

Parameter rem_port
Parameter rem_addr

remote address and UDP port (optional)

Parameter loc_port
Parameter loc_addr

local address and UDP port (optional)


Method readmsg

mapping readmsg()

Description

return the whole SNMP message in raw format


Method decode_asn1_msg

mapping decode_asn1_msg(mapping rawd)

Description

decode ASN1 data, if garbaged ignore it


Method to_pool

void to_pool(mapping rawd)

Description

decode raw pdu message and place in message pool


Method readmsg_from_pool

mapping readmsg_from_pool(int msgid)

Description

read decoded message from pool


Method get_request

int get_request(array(string) varlist, string|void rem_addr, int|void rem_port)

Description

GetRequest-PDU call

Parameter varlist

an array of OIDs to GET

Parameter rem_addr
Parameter rem_port

remote address an UDP port to send request to (optional)

Returns

request ID


Method get_response

int get_response(mapping varlist, mapping origdata, int|void errcode, int|void erridx)

Description

GetResponse-PDU call

Parameter varlist

a mapping containing data to return

oid1 : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oid1


oid2 : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oid2


oidn : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oidn



Parameter origdata

original received decoded pdu that this response corresponds to

Parameter errcode

error code

Parameter erridx

error index

Returns

request ID


Method get_nextrequest

int get_nextrequest(array(string) varlist, string|void rem_addr, int|void rem_port)

Description

GetNextRequest-PDU call

Parameter varlist

an array of OIDs to GET

Parameter rem_addr
Parameter rem_port

remote address an UDP port to send request to (optional)

Returns

request ID


Method set_request

int set_request(mapping varlist, string|void rem_addr, int|void rem_port)

Description

SetRequest-PDU call

Parameter varlist

a mapping of OIDs to SET

oid1 : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oid1


oid2 : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oid2


oidn : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oidn



Parameter rem_addr
Parameter rem_port

remote address an UDP port to send request to (optional)

Returns

request ID

Example

// set the value of 1.3.6.1.4.1.1882.2.1 to "blah". object s=Protocols.SNMP.protocol(); s->snmp_community="mysetcommunity"; mapping req=(["1.3.6.1.4.1.1882.2.1": ({"str", "blah"})]); int id=s->set_request(req, "172.21.124.32");


Method trap

int trap(mapping varlist, string oid, int type, int spectype, int ticks, string|void locip, string|void remaddr, int|void remport)

Description

send an SNMP-v1 trap

Parameter varlist

a mapping of OIDs to include in trap

oid1 : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oid1


oid2 : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oid2


oidn : array
Array
string type

data type such as tick, oid, gauge, etc

mixed data

data to return for oidn



Parameter oid
Parameter type

generic trap-type

Parameter spectype

specific trap-type

Parameter ticks

uptime

Parameter locip

originating ip address of the trap

Parameter remaddr
Parameter remport

address and UDP to send trap to

Returns

request id

  Module Protocols.X

  Module Protocols.X.Extensions

  CLASS Protocols.X.Extensions.extension

Description

an abstract class used to provide features for implimenting X11 extensions. Provides no useful functionality on its own.


Method init

int init(object d)

Description

initialize the extension.

Parameter d

An object of type Protocols.X.Xlib.Display

  CLASS Protocols.X.Extensions.XTEST

Description

Provides support for the X11 XTEST extension.


Inherit extension

inherit extension : extension


Method create

void Protocols.X.Extensions.XTEST()

Description

Create object.


Method init

int init(object display)

Description

Initialize the XTEST extension. Returns 1 if successful.

Parameter display

Protocols.X.Display object


Method XTestFakeInput

void XTestFakeInput(string event_type, int detail, int delay, object|void window, int|void xloc, int|void yloc)

Description

Send a synthetic event to an X server.

Parameter event_type

Type of event to send. Possible values: KeyPress: 2, KeyRelease: 3, ButtonPress: 4, ButtonRelease: 5, MotionNotify: 6

Parameter detail

Button (for Button events) or Keycode (for Key events) to send

Parameter delay

Delay before the X server simulates event. 0 indicates zero delay.

Parameter window

Window object that a motion event occurrs in. If no window is provided, the root window will be used.

Parameter xloc

For motion events, this is the relative X distance or absolute X coordinates.

Parameter yloc

For motion events, this is the relative Y distance or absolute Y coordinates.


Method XTestGrabControl

void XTestGrabControl(int impervious)

Description

Cause the executing client to become impervious to server grabs. That is, it can continue to execute requests even if another client grabs the server.

Parameter impervious

A true (non zero) value causes the client to perform as described above. If false (zero), server returns to the normal state of being susceptible to server grabs.

  Module Protocols.XMLRPC

Description

This module implements most features of the XML-RPC standard (see http://xml-rpc.org/).

Translation rules for conversions from Pike datatypes to XML-RPC datatypes:

Pike

int
is translated to XML-RPC <int>. Pike
string
is translated to XML-RPC <string>. Pike
float
is translated to XML-RPC <double>. Pike
mapping
is translated to XML-RPC <struct>. Pike
array
is translated to XML-RPC <array>.

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.

Note

The XML-RPC <dateTime.iso8601> datatype is currently only partially implemented. It is decoded but cannot be encoded. Also, the code here does not assume any particular timezone (which is correct according to the specification). The Calendar module, however, seems to assume localtime.


Method decode_call

Call Protocols.XMLRPC.decode_call(string xml_input)

Description

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

See also

Call


Method decode_response

array|Fault Protocols.XMLRPC.decode_response(string xml_input)

Description

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

See also

Fault


Method encode_call

string Protocols.XMLRPC.encode_call(string method_name, array params)

Description

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


Method encode_response

string Protocols.XMLRPC.encode_response(array params)

Description

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


Method encode_response_fault

string Protocols.XMLRPC.encode_response_fault(int fault_code, string fault_string)

Description

Encodes a response fault containing a fault_code and a fault_string and returns the XML-RPC string representation.

  CLASS Protocols.XMLRPC.Call

Description

Represents a function call made to a XML-RPC server.

See also

decode_call()


Variable method_name

int method_name

Description

Represents <methodName> in the XML-RPC standard.


Variable params

array params

Description

Represents <params> in the XML-RPC standard where all datatypes have been converted to equivalent or similar datatypes in Pike.

  CLASS Protocols.XMLRPC.Fault

Description

Represents a fault response which can be one of the return values from a XML-RPC function call.

See also

decode_response()


Variable fault_code

int fault_code

Description

Represents faultCode in the XML-RPC standard.


Variable fault_string

int fault_string

Description

Represents faultString in the XML-RPC standard.

  CLASS Protocols.XMLRPC.Client

Description

This class implements an XML-RPC client that uses HTTP transport.

Example

   > Protocols.XMLRPC.Client client = Protocols.XMLRPC.Client("http://www.oreillynet.com/meerkat/xml-rpc/server.php");
   Result: Protocols.XMLRPC.Client("http://www.oreillynet.com/meerkat/xml-rpc/server.php");
   > client["system.listMethods"]();
   Result: ({ /* 1 element */
  		    ({ /* 9 elements */
  			"meerkat.getChannels",
  			"meerkat.getCategories",
  			"meerkat.getCategoriesBySubstring",
  			"meerkat.getChannelsByCategory",
  			"meerkat.getChannelsBySubstring",
  			"meerkat.getItems",
  			"system.listMethods",
  			"system.methodHelp",
  			"system.methodSignature"
  		    })
  		})
 

  Module Protocols.LPD

  CLASS Protocols.LPD.client

Description

A client for communicating with printers and print spoolers that support the BSD lpd protocol (RFC 1179).


Method set_job_type

int set_job_type(string type)

Description

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


Method set_job_name

int set_job_name(string name)

Description

Sets the name of the print job to name.


Method start_queue

int start_queue(string queue)

Description

Start the queue queue if not already printing.

Returns

Returns 0 if unable to connect, 1 otherwise.


Method send_job

string|int send_job(string queue, string job)

Description

Send print job consisting of data job to printer queue.

Returns

Returns 1 if success, 0 otherwise.


Method delete_job

int delete_job(string queue, int|void job)

Description

Delete job job from printer queue.

Returns

Returns 1 on success, 0 otherwise.


Method status

string|int status(string queue)

Description

Check the status of queue queue.

Returns

Returns 0 on failure, otherwise returns the status response from the printer.


Method create

void Protocols.LPD.client(string|void hostname, int|void portnum)

Description

Create a new LPD client connection.

Parameter hostname

Contains the hostname or ipaddress of the print host. if not provided, defaults to localhost.

Parameter portnum

Contains the port the print host is listening on. if not provided, defaults to port 515, the RFC 1179 standard.

  Module Protocols.Line

  CLASS Protocols.Line.simple

Description

Simple nonblocking line-oriented I/O.


Constant line_separator

constant line_separator

Description

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


Variable handle_data

function(string:void) handle_data

Description

If this variable has been set, multiple lines will be accumulated, until a line with a single '.' (period) is received. handle_data() will then be called with the accumulated data as the argument.

Note

handle_data() is one-shot, ie it will be cleared when it is called.

The line with the single '.' (period) will not be in the accumulated data.

See also

handle_command()


Method handle_command

void handle_command(string line)

Description

This function will be called once for every line that is received.

Overload this function as appropriate.

Note

It will not be called if handle_data() has been set.

line will not contain the line separator.

See also

handle_data()


Method send

void send(string s)

Description

Queue some data to send.

See also

handle_command() , handle_data() , disconnect()


Method do_timeout

void do_timeout()

Description

This function is called when a timeout occurrs.

Overload this function as appropriate.

The default action is to shut down the connection immediately.

See also

create() , touch_time()


Method touch_time

void touch_time()

Description

Reset the timeout timer.

See also

create() , do_timeout()


Method read_line

string read_line()

Description

Read a line from the input.

Returns

Returns 0 when more input is needed. Returns the requested line otherwise.

Note

The returned line will not contain the line separator.

See also

handle_command() , line_separator


Method read_callback

void read_callback(mixed ignored, string data)

Description

Called when data has been received.

Overload as appropriate.

Calls the handle callbacks repeatedly until no more lines are available.

See also

handle_data() , handle_command() , read_line()


Variable send_q

ADT.Queue send_q

Description

Queue of data that is pending to send.

The elements in the queue are either strings with data to send, or 0 (zero) which is the end of file marker. The connection will be closed when the end of file marker is reached.

See also

send() , disconnect()


Method disconnect

void disconnect()

Description

Disconnect the connection.

Pushes an end of file marker onto the send queue send_q .

Note

Note that the actual closing of the connection is delayed until all data in the send queue has been sent.

No more data will be read from the other end after this function has been called.


Method close_callback

void close_callback()

Description

This function is called when the connection has been closed at the other end.

Overload this function as appropriate.

The default action is to shut down the connection on this side as well.


Method create

void Protocols.Line.simple(Stdio.File con, int|void timeout)

Description

Create a simple nonblocking line-based protocol handler.

con is the connection.

timeout is an optional timeout in seconds after which the connection will be closed if there has been no data sent or received.

If timeout is 0 (zero), no timeout will be in effect.

See also

touch_time() , do_timeout()

  CLASS Protocols.Line.smtp_style

Description

Nonblocking line-oriented I/O with support for sending SMTP-style codes.


Inherit simple

inherit simple : simple


Variable errorcodes

mapping(int:string|array(string)) errorcodes

Description

Mapping from return-code to error-message.

Overload this constant as apropriate.


Method send

void send(int(100..999) code, array(string)|string|void lines)

Description

Send an SMTP-style return-code.

code is an SMTP-style return-code.

If lines is omitted, errorcodes will be used to lookup an appropriate error-message.

If lines is a string, it will be split on '\n' (newline), and the error-code interspersed as appropriate.

See also

errorcodes

  CLASS Protocols.Line.imap_style

Description

Nonblocking line-oriented I/O with support for reading literals.


Inherit simple

inherit simple : simple


Variable literal_length

int literal_length

Description

Length in bytes of the literal to read.


Variable handle_literal

function(string:void) handle_literal

Description

If this variable has been set, literal_length bytes will be accumulated, and this function will be called with the resulting data.

Note

handle_literal() is one-shot, ie it will be cleared when it is called.


Variable handle_line

function(string:void) handle_line

Description

This function will be called once for every line that is received.

Note

This API is provided for backward compatibility; overload handle_command() instead.

See also

Protocols.Line.simple()->handle_command()


Method handle_command

void handle_command(string line)

Description

Function called once for every received line.


Method expect_literal

void expect_literal(int length, function(string:void) callback)

Description

Enter literal reading mode.

Sets literal_length and handle_literal() .

See also

literal_length , handle_literal()

  Module Protocols.SMTP

  CLASS Protocols.SMTP.client


Inherit protocol

inherit protocol : protocol


Constant reply_codes

constant reply_codes

Description

A mapping(int:string) that maps SMTP return codes to english textual messages.


Method create

void Protocols.SMTP.client()
void Protocols.SMTP.client(Stdio.File server)
void Protocols.SMTP.client(string server, void|int port)

Description

Creates an SMTP mail client and connects it to the the server provided. The server parameter may either be a string witht the hostnam of the mail server, or it may be a file object acting as a mail server. If server is a string, than an optional port parameter may be provided. If no port parameter is provided, port 25 is assumed. If no parameters at all is provided the client will look up the mail host by searching for the DNS MX record.

Throws

Throws an exception if the client fails to connect to the mail server.


Method send_message

void send_message(string from, array(string) to, string body)

Description

Sends a mail message from from to the mail addresses listed in to with the mail body body . The body should be a correctly formatted mail DATA block, e.g. produced by MIME.Message .

See also

simple_mail

Throws

If the mail server returns any other return code than 200-399 an exception will be thrown.


Method simple_mail

void simple_mail(string to, string subject, string from, string msg)

Description

Sends an e-mail. Wrapper function that uses send_message .

Note

Some important headers are set to: "Content-Type: text/plain; charset=iso-8859-1" and "Content-Transfer-Encoding: 8bit". "Date:" header isn't used at all.

Throws

If the mail server returns any other return code than 200-399 an exception will be thrown.


Method verify

array(int|string) verify(string addr)

Description

Verifies the mail address addr against the mail server.

Returns
Array
int code

The numerical return code from the VRFY call.

string message

The textual answer to the VRFY call.


Note

Some mail servers does not answer truthfully to verfification queries in order to prevent spammers and others to gain information about the mail addresses present on the mail server.

Throws

If the mail server returns any other return code than 200-399 an exception will be thrown.

  Module Protocols.TELNET

Description

Implements TELNET as described by RFC 764 and RFC 854

Also implements the Q method of TELNET option negotiation as specified by RFC 1143.


Inherit TelnetCodes

inherit TelnetCodes : TelnetCodes


Inherit Telopts

inherit Telopts : Telopts

  CLASS Protocols.TELNET.TelnetCodes

Description

Table of IAC-codes.

  CLASS Protocols.TELNET.Telopts

Description

Table of TELNET options.

  CLASS Protocols.TELNET.protocol

Description

Implementation of the TELNET protocol.


Variable fd

static object fd

Description

The connection.


Variable cb

static mapping cb

Description

Mapping containing extra callbacks.


Variable id

static mixed id

Description

Value to send to the callbacks.


Variable write_cb

static function(mixed|void:string) write_cb

Description

Write callback.


Variable read_cb

static function(mixed:void) read_cb

Description

Read callback.


Variable close_cb

static function(mixed|void:void) close_cb

Description

Close callback.


static array(int) remote_options
static array(int) local_options

Description

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


Variable to_send

static string to_send

Description

Data queued to be sent.


Variable done

static int done

Description

Indicates that connection should be closed


Variable nonblocking_write

static int nonblocking_write

Description

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


Method enable_write

void enable_write()

Description

Turns on the write callback if apropriate.


Method disable_write

void disable_write()

Description

Turns off the write callback if apropriate.


Method write

void write(string s)

Description

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

Parameter s

String to send.


Method write_raw

void write_raw(string s)

Description

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

Parameter s

String with raw telnet data to send.


Method close

void close()

Description

Closes the connetion neatly


Method send_data

void send_data()

Description

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


Method send_synch

void send_synch()

Description

Sends a TELNET synch command.


Method send_DO

void send_DO(int option)

Description

Starts negotiation to enable a TELNET option.

Parameter option

The option to enable.


Method send_DONT

void send_DONT(int option)

Description

Starts negotiation to disable a TELNET option.

Parameter option

The option to disable.


Variable synch

static int synch

Description

Indicates wether we are in synch-mode or not.


Method got_oob

void got_oob(mixed ignored, string s)

Description

Callback called when Out-Of-Band data has been received.

Parameter ignored

The id from the connection.

Parameter s

The Out-Of-Band data received.


Method call_read_cb

void call_read_cb(string data)

Description

Calls read_cb() .

Specifically provided for overloading


Method got_data

void got_data(mixed ignored, string line)

Description

Callback called when normal data has been received. This function also does most of the TELNET protocol parsing.

Parameter ignored

The id from the connection.

Parameter s

The received data.


Method set_write_callback

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

Description

Sets the callback to be called when it is clear to send.

Parameter w_cb

The new write callback.


Method setup

void setup()

Description

Called when the initial setup is done.

Created specifically for overloading


Method create

void Protocols.TELNET.protocol(object f, function(mixed:void) r_cb, function(mixed|void:string) w_cb, function(mixed|void:void) c_cb, mapping callbacks, mixed|void new_id)

Description

Creates a TELNET protocol handler, and sets its callbacks.

Parameter f

File to use for the connection.

Parameter r_cb

Function to call when data has arrived.

Parameter w_cb

Function to call when data can be sent.

Parameter c_cb

Function to call when the connection is closed.

Parameter callbacks

Mapping with callbacks for the various TELNET commands.

Parameter new_id

Value to send to the various callbacks.

  CLASS Protocols.TELNET.LineMode

Description

Line-oriented TELNET protocol handler.


Inherit protocol

inherit protocol : protocol

  CLASS Protocols.TELNET.Readline

Description

Line-oriented TELNET protocol handler with Stdio.Readline support.


Inherit LineMode

inherit LineMode : LineMode