new

init

readsize

The number of bytes to request (but not expect) from the socket at any one time. Defaults to 1500 to ensure that an ethernet packet will be read in one call. Do not set this excessively high. Likewise, setting it too low will result in excessive polls.

disconnectonmax

A boolean indicating whether to disconnect on exceeding maxobjectsize bytes, maxnamesize or maxobjectdepth in a single object. The default, 0, will continue to read and parse the object, but will not save more of the object's data or attributes into memory.

maxobjectsize

The maximum number of bytes allowed in a single object. There is no default. This is intended as protection against an excessively large packet.

maxobjectdepth

The maximum number of subtags allowed in a single object. There is no default.

maxnamesize

The maximum length of a single tag name, eg, the 'foo' in '<foo/>'. There is no default. Note that this is applied against every tag, not just the parent tag. This is intended as protecting against a really long <taaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaag>, which may still consume memory if the maxobject size is exceeded and disconnectonmax is left at 0.

debug

A debug qualifier. If set to '1', will show all debug messages. If set to a comma-seperated string, will show all debug messages generated by those subroutines.

The various 'max' settings are enforced by ->do_read(). Calling ->parse_more() directly will not incur the dubious protections afforded by this.

resolve

Note that no DNSSEC or TSIG verification is done.

resolved

The ordering is done according to the method set out in RFC2782(DNS SRV Records). Of particular note is page 3, where a randomisation function is applied to the ordering of SRV RRs with equal priority. Thus, each time this function is called, it may return a different ordering of IPs.

bgresolve

bgresolved

connect

Takes a hash of values as follows:

Host

The Host (name or IP address) to connect to. Default is no host, and thus no connection. Note that if a name of the Host is used, then gethostbyname will be implicitly used by IO::Socket::INET, blocking the application whilst doing so. Calling applications may wish to avail themselves of the ->resolve() methods listed earlier to avoid this.

Port

The port to connect to on the remote host. Defaults to 5222.

Domain

The domain to request on the remote Host. Defaults to the value of the Host option. The meaning of this depends on the connection type (StreamXMLNS). If connecting as a client, refers to the domain that the Username and Password credentials belong to. If connecting as a component, refers to the domain that this connection wants to bind as.

UseSSL

Initiate a SSL/TLS connection immediately on connecting, for example, if you are connecting to a server which offers SSL on an alternative port. Defaults to 0. This is used internally to redo the connection.

UseTLS

Negotiate a TLS connection if <starttls> is listed as one of the connection features, and IO::Socket::SSL is available. Defaults to 1, as everyone likes encryption.

MustEncrypt

The connection must be encrypted before considering the connection to be opened. This defaults to 0. If this is set to 1, and IO::Socket::SSL is not available, the connection will fail.

JustConnect

This simply opens a connection and returns without having sent any packets, except for any required to initiate SSL if requested. The calling program is responsible for sending any initial packets down the link, and responding to any packets received. Defaults to 0.

JustConnectAndStream

This simply opens a connection and sends the initial '<stream:stream>' tag, then returns. The default is 0. It is used internally for a number of things, each time a new '<stream:stream>' tag needs to be sent, which is surprisingly often (once when connect, once after TLS is negotiated, and once after SASL has been negotiated).

AllowRedirect

This checks to see if the server domain returned to us is the same as the Domain that was requested. The default, 1, allows this check to be skipped.

StreamXMLNS

The type of connection that we're telling the server this is. Defaults to 'jabber:client'. For component connections, use 'jabber:component:accept', and for servers, use 'jabber:server'. Or use the "ConstXMLNS" method documented towards the end (use 'client' or 'component').

StreamXMLLANG

The default language used over the connection, as per xml:lang. Defaults to undef (not sent).

StreamId

A client-initiated Identifier. RFC3920 4.4 says that the stream id SHOULD only be used from the receiving entity to the intiating entity. However, some applications may think otherwise. Defaults to undef (not sent).

Timeout

The number of seconds to hang around whilst waiting for a connection to succeed. Defaults to 30. Note that the time taken for connect may be more than this, as the same value is used in the connection, SSL negotiation and waiting for the remote server to respond phases.

Note that during the SSL negotiation, the application will block, due to the perl SSL libraries not obviously supporting a backgroundable method.

Version

The version to declare to the remote Jabber server. The default, '1.0', attempts to steer the conversation along the lines of RFC3920, xmpp-core.

SSL*

Any option beginning with 'SSL' will be passed to IO::Socket::SSL as-is, which may be useful if you are expecting to exchange certificate information. No values are set up by default.

OwnSocket

A boolean which indicates that a socket has previously been created by methods unknown to this library, and stored via ->socket(). Thus, ->connect() doesn't actually have to do a TCP connection, and can just continue on with the connection methods.

Note for people with their own connection requirements: The ->connect() method is comparitively simple (ha!); just initiating a TCP connection and setting up handlers to negotiate TLS. Those wishing to set up their own connection handlers are welcome to do so, but search this library's code for the string 'grok incomplete' before doing so.

Those concerned about the ?xml attributes emitted by the remote end can reference the ->xml_version(), ->xml_encoding() and ->xml_standalone) methods.

bgconnect

Returns 1 if the TCP connection could be started, and 0 if not. If this method returns 0, you probably have bigger problems.

Note: The ->bgconnect() method just calls ->connect() with the background flag set.

bgconnected

        RunProcess - Invoke ->process() internally
        ProcessTime - time to pass to ->process() (default 0 )

If RunProcess is not specified, you will have to invoke ->process() seperately.

authenticate

Username

The username to authenticate as.

Password

The password to use.

Resource

Specify a resource method to use. If a Resource is not specified, a default value of 'Jabber::Lite' is used. Note that the Resource accepted by the server may be different; use ->connect_jid() to find out what the server considers the Resource to be.

Domain

The domain to use if the authentication method requires it. Defaults to the value specified for ->connect().

ComponentSecret

The secret to use if authenticating as a component, or if the chosen authentication method requires just a password, not a username.

Method

The preferred authentication method to use. Either 'sasl' or 'jabber:iq:auth'. The default is 'jabber:iq:auth' (JEP-0078), unless the server has supplied a list of authentication mechanisms as per xmpp-core (RFC3920), in which case 'sasl' is used.

Mechanism

A preferred mechanism to use for authentication. The library will try to use any available mechanisms that are considered more secure than the one supplied, but should not try mechanisms that are considered less secure. The mechanisms available, in order of highest security to lowest, are:

DoBind

A boolean indicating whether to bind the nominated resource if so requested by the remote server. The default, 1, is for applications that do not wish to deal with this step, or for people for whom urn:ietf:params:xml:ns:xmpp-bind is at a significant altitude. If you know what you are doing, set this to 0, and be sure to read the ->bind() method. Note that if the server requires binding, and this is not done, the server will most probably return a '<not-authorized>' stanza back and disconnect (so says RFC3920 section 7).

DoSession

A boolean indicating whether to initiate a session if so requested by the remote server. The default, 1, is for applications that do not wish to deal with this step, or for people for whom urn:ietf:params:xml:ns:xmpp-session is at a significant altitude. If you know what you are doing, set this to 0, and be sure to read the ->session() method. Note that if the server requires sessions, and this is not done, the server will most probably return a '<not-authorized>' stanza back and disconnect (so says RFC3921 section 3).

RandomResource

A boolean indicating whether a random Resource identifier can be used in the case of conflicts. Defaults to 0.

It returns 1 on success, and 0 on failure.

bgauthenticate

Note: This method will block on older servers where ->listauths() has to ask for a packet.

bgauthenticated

        RunProcess - Invoke ->process() internally
        ProcessTime - time to pass to ->process() (default 0 )

If RunProcess is not specified, you will have to invoke ->process() seperately.

auth

AuthSend

stream_features

Note that during the ->connect() and ->authenticate() phases, certain of these features may get 'used', and thus not returned by the server the next time it issues a <stream:features> tag.

listauths

The return value is either an @array or %hash of possible authentication methods and mechanisms depending on the 'Want' option ('array' or 'hash'), arranged as per 'method-mechanism', eg 'sasl-digest-md5' or 'jabber:iq:auth-plain'.

This method should be called after ->connect(), obviously.

Note: If Ask (or JustAsk) is specified, this method will call ->process(), until it gets the reply it is expecting. If other packets are expected during this time, use ->register_handler() to set up callbacks for them, making sure that any <iq> packets in the 'jabber:iq:auth' namespace (<query> subtag) are not swallowed.

session

Process

A string of either 'if-required' or 'always', indicating whether to always do so, or just if required to do so.

Returns 1 if successful, 0 otherwise.

bgsessioned

bind

Process

A string of either 'if-required' or 'always', indicating whether to always do so, or just if required to do so.

Resource

A Resource string to use.

AllowRandom

Start using a random resource if the requested Resource was rejected by the server.

Returns 1 if successful, 0 otherwise. If successful, will update the value used by ->connect_jid().

bgbind

bgbinded

clear_handlers

Alternatively, specifying a 'Class' of 'connect' and 'authenticate' will remove just the handlers created by ->connect() and ->authenticate() respectively.

WARNING: The standard ->connect() and ->authenticate() (and/or their bg varients) require their configured handlers to be in place. Do not execute ->clear_handlers() between ->connect() and ->authenticate, lest your application suddenly fail to work.

This takes a hash of optional arguments, being 'Type' and 'Class'. The 'Type' is the same as the Type supplied to 'register_handler', and if supplied, will delete all callbacks of that Type. The 'Class' is the same as the optional Class supplied to 'register_handler', and if supplied, will delete all callbacks of that class.

register_handler

Each handler is invoked with two arguments; the object representing the current packet, and a value received from calls to previous handlers. so-called 'parcel' or 'persistent' data. The return value is either the "r_HANDLED" constant or parcel/persistent data to be handed to the next handler.

Note: See notes regarding handlers under ->process().

Note: The ->connect() and ->authenticate() methods use handlers to function.

Note: A third argument can be supplied to indicate the 'class' of this handler, for usage with ->clear_handlers(). If not supplied, defaults to 'user'.

register_interval

Interval

The frequency which this subroutine should be executed, in seconds.

Sub

A reference to the actual subroutine. Since I keep forgetting how to do so myself, if you want to call an object-based method with your working object, you do so via 'Sub => sub { $objname->some_method(@_) }'

Argument

If supplied, will be supplied as the second argument.

Once

A boolean as to whether this routine should be executed just once (after Interval seconds). Defaults to 0.

Now

A boolean as to whether this routine's first execution should be the next time ->process() is invoked, or after Interval seconds have elapsed. Defaults to 0.

The subroutine is invoked with a single argument of the current connection object (in case you want to send something), and the value of the 'Argument' hash if supplied.

Note: These are executed as a side-effect of running ->process(). If you do not regularly invoke ->process() (or via ->start()), these timeouts will not be invoked. Executing ->process() from within the handler may cause odd things to happen.

register_beat

process

The values returned, which MUST be checked on each call, are:

        -2: Invalid XML was read.

        -1: EOF was reached.

         0: No action.  Data may or may not have been read.

         1: A complete object has been read, and is available for
            retrieval via get_latest().

         2: A complete object was read, but was eaten 
            by a defined handler.

Note that after a complete object has been read, any further calls to ->process() will not create additional objects until the current complete object has been retrieved via ->get_latest(). This does not apply if the object was eaten/accepted by a defined handler.

Note: ->process() is a wrapper around ->can_read() and ->do_read(), but it executes handlers as well. ->process() will return after every packet read (imho, a better behaviour than simply reading from the socket until the remote end stops sending us data).

send

Note that if you send non-XML data (gibberish or incomplete), thats your problem, not mine.

disconnect

abort

socket

Note: The library uses sysread() and send/syswrite() as required. Passing in filehandles that do not support these functions is probably a bad idea.

Note: There is some juggling of sockets within the ->connect() method when SSL starts up. Whilst a select() on the original, or parent socket will probably still work, it would probably be safer to not include the socket returned by ->socket() in any select() until the ->connect() and ->authenticate() methods have returned.

can_read

can_write

do_read

-2 if the parsing indicated invalid XML,

-1 if the socket reached EOF,

0 if the socket was ok and data was read happily.

1 if there is a complete object (use ->get_latest() )

Applications MUST check the return value on each call. Takes a hash of optional arguments, the most important being:

        PendingOnly (default 0) - Only process the pending data, do not
        attempt to read from the socket.

->do_read() also checks the maxobjectsize, maxobjectdepth and maxnamesize.

->do_read() also checks the likely size of the object as it is being read. If it is larger than the maxobjectsize value passed to ->new/->init, the appropriate behaviour will be taken. Note that if the behaviour chosen is to continue parsing but not save (the default), then an attack consisting of <foo><foo><foo> repeated ad nauseum will still eventually exhaust memory.

This is because to properly parse the object, the parser must know at which point the object is at, meaning that the name of each <tag> must be stored.

is_eof

is_authenticated

is_connected

is_encrypted

connect_jid

_connect_starttls handler

_connect_handler handler

xml_version

xml_encoding

xml_standalone

get_latest

WARNING: This is a destructive process; a second call will return undef until another object has been read.

copy_latest

WARNING: This may return objects which are incomplete, and may not make too much sense. Supplying an argument which is not of this class may produce odd results.

clear_latest

newNode

A previously created object can be supplied instead.

newNodeFromStr

Note: If there was more than one object in the string, the remaining string is tossed away; you only get one object back.

insertTag

name

Note: No checking or escaping is done on the supplied name.

is_complete

getChildren

getTag

listAttrs

attr

xmlns

data

rawdata

parent

hide

hidechild

hidetree

toStr

If set to '0', '<stream>' will be output instead of '<stream/>', a highly important distinction when first connecting to Jabber servers (remember that a Jabber connection is really one long '<stream>' tag ).

GetXML

create_and_parse

Returns the new object (or undef), a success value, and any unprocessed text. Success values can be one of:

        -2 Invalid XML
        0 No errors
        1 Complete object

parse_more

        -2 if a parsing error was found.
        0 if no obvious bugs were found.
        1 if a complete object was found.

The parser, such as it is, will sometimes return text to be prepended with any new text. If the calling application does not keep track of the returned text and supply it the next time, the parser's behaviour is undefined. Most applications will be invoking ->parse_more() via ->do_read() or ->process(), so this situation will not come up.

This needs

An optional second argument can be supplied which, if 1, will inhibit the saving of most text to memory. This is used by do_read to indicate that an excessively-large object is being read.

_curstatus

encode

decode

expandEntity

This function is non-intuitive, as it will replace 'amp' with 'amp', but 'pre-defined-escape' with 'text that was declared in the <!ENTITY> declaration for pre-defined-escape'. Its prime usage is in the storage of hopefully-compliant-XML data into the object, and is used as part of the data verification routines.

ConstXMLNS

_got_Net_DNS

_got_Digest_SHA1

_got_Digest_MD5

_got_Authen_SASL

_got_MIME_Base64

_got_IO_Socket_SSL

debug

Prints the supplied string, along with some other useful information, to STDERR, if the initial object was created with the debug flag.

version