.\" 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