Previous chapter To contents Next chapter

Chapter 13, Protocols

The Protocol modules is some helper modules that makes it easier for the pike programmer to use some of the protocols used on the internet.

13.1 Protocols.HTTP

METHOD
Protocols.HTTP.delete_url

SYNTAX
object(Protocols.HTTP.Query) delete_url(string url)
object(Protocols.HTTP.Query) delete_url(string url, mapping query_variables)
object(Protocols.HTTP.Query) delete_url(string url, mapping query_variables,  mapping request_headers)

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.

METHOD
Protocols.HTTP.get_url

SYNTAX
object(Protocols.HTTP.Query) get_url(string url)
object(Protocols.HTTP.Query) get_url(string url, mapping query_variables)
object(Protocols.HTTP.Query) get_url(string url, mapping query_variables,  mapping request_headers)

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.

METHOD
Protocols.HTTP.get_url_nice,
Protocols.HTTP.get_url_data

SYNTAX
array(string) get_url_nice(string url)
array(string) get_url_nice(string url, mapping query_variables)
array(string) get_url_nice(string url, mapping query_variables,  mapping request_headers)
string get_url_data(string url)
string get_url_data(string url, mapping query_variables)
string get_url_data(string url, mapping query_variables,  mapping request_headers)

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
Protocols.HTTP.post_url_nice,
Protocols.HTTP.post_url_data,
Protocols.HTTP.post_url

SYNTAX
array(string) post_url_nice(string url, mapping query_variables)
array(string) post_url_nice(string url, mapping query_variables,  mapping request_headers)
string post_url_data(string url, mapping query_variables)
string post_url_data(string url, mapping query_variables,  mapping request_headers)
object(Protocols.HTTP.Query) post_url(string url, mapping query_variables)
object(Protocols.HTTP.Query) post_url(string url, mapping query_variables,  mapping request_headers)

DESCRIPTION
Similar to the get_url class of functions, except that the query variables is sent as a post request instead of a get.

METHOD
Protocols.HTTP.put_url

SYNTAX
object(Protocols.HTTP.Query) put_url(string url)
object(Protocols.HTTP.Query) put_url(string url, string file)
object(Protocols.HTTP.Query) put_url(string url, string file, mapping query_variables)
object(Protocols.HTTP.Query) put_url(string url, string file, mapping query_variables,  mapping request_headers)

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.

METHOD
Protocols.HTTP.unentity

SYNTAX
string unentity(string s)

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

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

13.1.1 Protocols.HTTP.Query

CLASS
Protocols.HTTP.Query

DESCRIPTION
Open and execute a HTTP query.

METHOD
Protocols.HTTP.Query.set_callbacks,
Protocols.HTTP.Query.async_request

SYNTAX
object set_callbacks(function request_ok, function request_fail, mixed ...extra)
object async_request(string server, int port, string query);
object async_request(string server, int port, string query, mapping headers, void|string data);

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

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

request_fail(object httpquery,...extra args) is called if the connection fails.

variable int ok Tells if the connection is successfull. variable int errno Errno copied from the connection.

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

variable string protocol Protocol string, ie "HTTP/1.0".

variable int status variable string status_desc Status number and description (ie, 200 and "ok").

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

variable mapping async_dns Set this to an array of Protocols.DNS.async_clients, if you wish to limit the number of outstanding DNS requests. Example: async_dns=allocate(20,Protocols.DNS.async_client)();

RETURNS
the called object

METHOD
Protocols.HTTP.Query.cast

SYNTAX
array cast("array")

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

METHOD
Protocols.HTTP.Query.cast

SYNTAX
mapping cast("mapping")

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

METHOD
Protocols.HTTP.Query.cast

SYNTAX
string cast("string")

DESCRIPTION
Gives back the answer as a string.

METHOD
Protocols.HTTP.Query.data

SYNTAX
string data()

DESCRIPTION
Gives back the data as a string.

METHOD
Protocols.HTTP.Query.downloaded_bytes

SYNTAX
int downloaded_bytes()

DESCRIPTION
Gives back the number of downloaded bytes.

METHOD
Protocols.HTTP.Query.thread_request

SYNTAX
object thread_request(string server, int port, string query);
object 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 this 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

METHOD
Protocols.HTTP.Query.total_bytes

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

object(pseudofile) file() object(pseudofile) file(mapping newheaders,void|mapping removeheaders) object(pseudofile) datafile(); Gives back a pseudo-file object, with the method 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.

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

void async_fetch(function done_callback); Fetch all data in background.

METHOD
Protocols.HTTP.Query.`

SYNTAX
int `()()

DESCRIPTION
Wait for connection to complete.

RETURNS
1 on successfull connection, 0 if failed

13.2 Protocols.LysKOM

13.2.1 Protocols.LysKOM.Session

CLASS
Protocols.LysKOM.Session

DESCRIPTION
variable user This variable contains the person that are logged in.

METHOD
Protocols.LysKOM.Session.create

SYNTAX
void create(string server)
void create(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
   advanced
   "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
Protocols.LysKOM.Session.create_person

SYNTAX
object create_person(string name, string password)

DESCRIPTION
Create a person, which will be logged in.

RETURNS
the new person object

METHOD
Protocols.LysKOM.Session.create_text

SYNTAX
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" are given, this function will be called when the text is 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)           
        what text(s) is commented
   "foot_to" : Text|array(Text)           
        what text(s) is footnoted
   
   "anonymous" : int(0..1)                
        send text anonymously
])

NOTE
The above marked with a '*' is only available on a protocol 10 server. A LysKOM error will be thrown if the call fails.

SEE ALSO
Conference.create_text, Text.comment and Text.footnote

METHOD
Protocols.LysKOM.Session.login

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

DESCRIPTION
Performs a login. Returns 1 on success or throws a lyskom error.

RETURNS
the called object

METHOD
Protocols.LysKOM.Session.logout

SYNTAX
object logout()

DESCRIPTION
Logouts from the server.

RETURNS
the called object

METHOD
Protocols.LysKOM.Session.send_message

SYNTAX
object send_message(string message,  mapping options)

DESCRIPTION
Sends a message.

options is a mapping that may contain:

([
   "recpt" : Conference recipient conference
])

METHOD
Protocols.LysKOM.Session.try_complete_person

SYNTAX
array(object) try_complete_person(string orig)

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

13.2.2 Protocols.LysKOM.Connection

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
Protocols.LysKOM.Connection./call/,
Protocols.LysKOM.Connection.async_/call/,
Protocols.LysKOM.Connection.async_cb_/call/

SYNTAX
mixed /call/(mixed ...args)
object async_/call/(mixed ...args)
object async_cb_/call/(function callback, mixed ...args)

DESCRIPTION
Do a call to the server. This really clones a request object, and initialises it. /call/ 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 is asynchronous calls, returning the initialised request object.

variable int protocol_level variable string session_software variable string software_version Description of the connected server.

METHOD
Protocols.LysKOM.Connection.create

SYNTAX
void create(string server)
void create(string server, mapping options)

DESCRIPTION
([
   "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
   advanced
   "port" : int(0..65535)  server port (default is 4894)
   "whoami" : string       present as this user
                         (default is from uid/getpwent and hostname)
])

13.2.3 Protocols.LysKOM.Request

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.

13.2.3.1 Protocols.LysKOM.Request._Request

CLASS
Protocols.LysKOM.Request._Request

DESCRIPTION
This is the main request class. All lyskom request classes inherits this class.

METHOD
Protocols.LysKOM.Request._Request.async,
Protocols.LysKOM.Request._Request.sync

SYNTAX
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
Protocols.LysKOM.Request._Request._reply,
Protocols.LysKOM.Request._Request.reply

SYNTAX
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
Protocols.LysKOM.Request._Request.`

SYNTAX
mixed `()()

DESCRIPTION
wait for the call to finish.

variable int ok tells if the call is executed ok variable object error how the call failed The call is completed if (ok||error).

METHOD
Protocols.LysKOM.Request._Request._async,
Protocols.LysKOM.Request._Request._sync

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

13.3 Protocols.DNS

DESCRIPTION

13.3.1 Protocols.DNS.client

CLASS
Protocols.DNS.client

DESCRIPTION
Synchronous DNS client.

METHOD
Protocols.DNS.client.create

SYNTAX
void create()
void create(void|string|array server,  void|int|array domain)

DESCRIPTION

METHOD
Protocols.DNS.client.gethostbyname,
Protocols.DNS.client.gethostbyaddr

SYNTAX
array gethostbyname(string hostname)
array gethostbyaddr(string hostip)

DESCRIPTION
Querys the host name or ip from the default or given DNS server. The result is a mapping with three elements,
({
   string hostname  [0] hostname
   array(string) ip [1] ip number(s)
   array(string) ip [2] dns name(s)
})

METHOD
Protocols.DNS.client.get_primary_mx

SYNTAX
string get_primary_mx(string hostname)

DESCRIPTION
Querys the primary mx for the host.

RETURNS
the hostname of the primary mail exchanger

Previous chapter To contents Next chapter