.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::XMPP::Namespaces 3pm" .TH Net::XMPP::Namespaces 3pm "2014-04-11" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::XMPP::Namespaces \- In depth discussion on how namespaces are handled .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& Net::XMPP::Namespaces provides an depth look at how Net::XMPP handles \& namespacs, and how to add your own custom ones. It also serves as the \& storage bin for all of the Namespace information Net::XMPP requires. .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" .Vb 3 \& XMPP as a protocol is very well defined. There are three main top \& level packets (message, iq, and presence). There is also a way to \& extend the protocol in a very clear and strucutred way, via namespaces. \& \& Two major ways that namespaces are used in Jabber is for making the \& a generic wrapper, and as a way for adding data to any packet via \& a child tag . We will use to represent the packet, but in \& reality it could be any child tag: , , , etc. \& \& The Info/Query packet uses namespaces to determine the type of \& information to access. Usually there is a tag in the \& that represents the namespace, but in fact it can be any tag. The \& definition of the Query portion, is the first tag that has a namespace. \& \& \& \& or \& \& \& \& After that Query stanza can be any number of other stanzas ( tags) \& you want to include. The Query packet is represented and available by \& calling GetQuery() or GetChild(), and the other namespaces are \& available by calling GetChild(). \& \& The X tag is just a way to piggy back data on other packets. Like \& embedding the timestamp for a message using jabber:x:delay, or signing \& you presence for encryption using jabber:x:signed. \& \& To this end, Net::XMPP has sought to find a way to easily, and clearly \& define the functions needed to access the XML for a namespace. We will \& go over the full docs, and then show two examples of real namespaces so \& that you can see what we are talking about. .Ve .SS "Overview" .IX Subsection "Overview" .Vb 6 \& To avoid a lot of nasty modules populating memory that are not used, \& and to avoid having to change 15 modules when a minor change is \& introduced, the Net::XMPP modules have taken AUTOLOADing to the \& extreme. Namespaces.pm is nothing but a set of function calls that \& generates a big hash of hashes. The hash is accessed by the Stanza.pm \& AUTOLOAD function to do something. (This will make sense, I promise.) \& \& Before going on, I highly suggest you read a Perl book on AUTOLOAD and \& how it works. From this point on I will assume that you understand it. \& \& When you create a Net::XMPP::IQ object and add a Query to it (NewChild) \& several things are happening in the background. The argument to \& NewChild is the namespace you want to add. (custom\-namespace) \& \& Now that you have a Query object to work with you will call the GetXXX \& functions, and SetXXX functions to set the data. There are no defined \& GetXXX and SetXXXX functions. You cannot look in the Namespaces.pm \& file and find them. Instead you will find something like this: \& \& &add_ns(ns => "mynamespace", \& tag => "mytag", \& xpath => { \& JID => { type=>\*(Aqjid\*(Aq, path => \*(Aq@jid\*(Aq }, \& Username => { path => \*(Aqusername/text()\*(Aq }, \& Test => { type => \*(Aqmaster\*(Aq } \& } \& ); \& \& When the GetUsername() function is called, the AUTOLOAD function looks \& in the Namespaces.pm hash for a "Username" key. Based on the "type" of \& the field (scalar being the default) it will use the "path" as an XPath \& to retrieve the data and call the XPathGet() method in Stanza.pm. \& \& Confused yet? .Ve .SS "Net::XMPP private namespaces" .IX Subsection "Net::XMPP private namespaces" .Vb 4 \& Now this is where this starts to get a little sticky. When you see a \& namespace with _\|_netxmpp_\|_, or _\|_netjabber_\|_ from Net::Jabber, at the \& beginning it is usually something custom to Net::XMPP and NOT part of \& the actual XMPP protocol. \& \& There are some places where the structure of the XML allows for \& multiple children with the same name. The main places you will see \& this behavior is where you have multiple tags with the same name and \& those have children under them (jabber:iq:roster). \& \& In jabber:iq:roster, the tag can be repeated multiple times, \& and is sort of like a mini\-namespace in itself. To that end, we treat \& it like a separate namespace and defined a _\|_netxmpp_\|_:iq:roster:item \& namespace to hold it. What happens is this, in my code I define that \& the s tag is "item" and anything with that tag name is to create \& a new Net::XMPP::Stanza object with the namespace \& _\|_netxmpp_\|_:iq:roster:item which then becomes a child of the \& jabber:iq:roster Stanza object. Also, when you want to add a new item \& to a jabber:iq:roster project you call NewQuery with the private \& namespace. \& \& I know this sounds complicated. And if after reading this entire \& document it is still complicated, email me, ask questions, and I will \& monitor it and adjust these docs to answer the questions that people \& ask. .Ve .SS "\fIadd_ns()\fP" .IX Subsection "add_ns()" .Vb 1 \& To repeat, here is an example call to add_ns(): \& \& &add_ns(ns => "mynamespace", \& tag => "mytag", \& xpath => { \& JID => { type=>\*(Aqjid\*(Aq, path => \*(Aq@jid\*(Aq }, \& Username => { path => \*(Aqusername/text()\*(Aq }, \& Test => { type => \*(Aqmaster\*(Aq } \& } \& ); \& \& ns \- This is the new namespace that you are trying to add. \& \& tag \- This is the root tag to use for objects based on this namespace. \& \& xpath \- The hash reference passed in the add_ns call to each name of \& entry tells Net::XMPP how to handle subsequent GetXXXX(), SetXXXX(), \& DefinedXXXX(), RemoveXXXX(), AddXXXX() calls. The basic options you \& can pass in are: \& \& type \- This tells Stanza how to handle the call. The possible \& values are: \& \& array \- The value to set and returned is an an array \& reference. For example, in jabber:iq:roster. \& \& child \- This tells Stanza that it needs to look for the \& _\|_netxmpp_\|_ style namesapced children. AddXXX() adds \& a new child, and GetXXX() will return a new Stanza \& object representing the packet. \& \& flag \- This is for child elements that are tags by themselves: \& . Since the presence of the tag is what is \& important, and there is no cdata to store, we just call \& it a flag. \& \& jid \- The value is a Jabber ID. GetXXX() will return a \& Net::XMPP::JID object unless you pass it "jid", then it \& returns a string. \& \& master \- The GetXXX() and SetXXX() calls return and take a \& hash representing all of the GetXXX() and SetXXX() \& calls. For example: \& \& SetTest(foo=>"bar", \& bar=>"baz"); \& \& Translates into: \& \& SetFoo("bar"); \& SetBar("baz"); \& \& GetTest() would return a hash containing what the \& packet contains: \& \& { foo=>"bar", bar=>"baz" } \& \& raw \- This will stick whatever raw XML you specify directly \& into the Stanza at the point where the path specifies. \& \& scalar \- This will set and get a scalar value. This is the \& main workhorse as attributes and CDATA is represented \& by a scalar. This is the default setting if you do \& not provide one. \& \& special \- The special type is unique in that instead of a \& string "special", you actually give it an array: \& \& [ "special" , ] \& \& This allows Net::XMPP to be able to handle the \& SetXXXX() call in a special manner according to your \& choosing. Right now this is mainly used by \& jabber:iq:time to automatically set the time info in \& the correct format, and jabber:iq:version to set the \& machine OS and add the Net::Jabber version to the \& return packet. You will likely NOT need to use \& this, but I wanted to mention it. \& \& timestamp \- If you call SetXXX() but do not pass it anything, \& or pass it "", then Net::XMPP will place a \& timestamp in the xpath location. \& \& path \- This is the XPath path to where the bit data lives. The \& difference. Now, this is not full XPath due to the nature \& of how it gets used. Instead of providing a rooted path \& all the way to the top, it\*(Aqs a relative path ignoring what \& the parent is. For example, if the "tag" you specified was \& "foo", and the path is "bar/text()", then the XPath will be \& rooted in the XML of the packet. It will set and get \& the CDATA from: \& \& xxxxx \& \& For a flag and a child type, just specify the child element. \& Take a look at the code in this file for more help on what \& this means. Also, read up on XPath if you don\*(Aqt already know \& what it is. \& \& child \- This is a hash reference that tells Net::XMPP how to handle \& adding and getting child objects. The keys for the hash are \& as follows: \& \& ns \- the real or custom (_\|_netxmpp_\|_) namesapce to use for \& this child packet. \& \& skip_xmlns => 1 \- this tells Net::XMPP not to add an \& xmlns=\*(Aq\*(Aq into the XML for the child \& object. \& \& specify_name => 1 \- allows you to call NewChild("ns","tag") \& and specify the tag to use for the child \& object. This, IMHO, is BAD XML \& practice. You should always know what \& the tag of the child is and use an \& attribute or CDATA to change the type \& of the stanza. You do not want to use \& this. \& \& tag \- If you use specify_name, then this is the default tag \& to use. You do not want to use this. \& \& calls \- Array reference telling Net::XMPP what functions to create \& for this name. For most of the types above you will get \& Get, Set, Defined, and Remove. For child types you need to \& decide how you API will look and specify them yourself: \& \& ["Get","Defined"] \& ["Add"] \& ["Get","Add","Defined"] \& \& It all depends on how you want your API to look. \& \& Once more... The following: \& \& &add_ns(ns => "mynamespace", \& tag => "mytag", \& xpath => { \& JID => { type=>\*(Aqjid\*(Aq, path => \*(Aq@jid\*(Aq }, \& Username => { path => \*(Aqusername/text()\*(Aq }, \& Test => { type => \*(Aqmaster\*(Aq } \& } \& ); \& \& generates the following API calls: \& \& GetJID() \& SetJID() \& DefinedJID() \& RemoveJID() \& GetUsername() \& SetUsername() \& DefinedUsername() \& RemoveUsername() \& GetTest() \& SetTest() .Ve .SS "Wrap Up" .IX Subsection "Wrap Up" .Vb 5 \& Well. I hope that I have not scared you off from writing a custom \& namespace for you application and use Net::XMPP. Look in the \& Net::XMPP::Protocol manpage for an example on using the add_ns() \& function to register your custom namespace so that Net::XMPP can \& properly handle it. .Ve .SH "AUTHOR" .IX Header "AUTHOR" Ryan Eatmon .SH "COPYRIGHT" .IX Header "COPYRIGHT" This module is free software, you can redistribute it and/or modify it under the \s-1LGPL.\s0