1Net::XMPP::Presence(3)User Contributed Perl DocumentationNet::XMPP::Presence(3)
2
6 Net::XMPP::Presence - XMPP Presence Module
7
9 Net::XMPP::Presence is a companion to the Net::XMPP module.
10 It provides the user a simple interface to set and retrieve all
11 parts of an XMPP Presence.
12
14 A Net::XMPP::Presence object is passed to the callback function for
15 the message. Also, the first argument to the callback functions is
16 the session ID from XML::Streams. There are some cases where you
17 might want this information, like if you created a Client that
18 connects to two servers at once, or for writing a mini server.
19 use Net::XMPP;
21 sub presence {
23 my ($sid,$Pres) = @_;
24 .
25 .
26 .
27 }
28 You now have access to all of the retrieval functions available.
30 To create a new presence to send to the server:
32 use Net::XMPP;
34 $Pres = new Net::XMPP::Presence();
36 Now you can call the creation functions below to populate the tag
38 before sending it.
39
41 Retrieval functions
42 GetTo() - returns the value in the to='' attribute for the
44 GetTo("jid") <presence/>. If you specify "jid" as an argument
45 then a Net::XMPP::JID object is returned and
46 you can easily parse the parts of the JID.
47 $to = $Pres->GetTo();
49 $toJID = $Pres->GetTo("jid");
50 GetFrom() - returns the value in the from='' attribute for the
52 GetFrom("jid") <presence/>. If you specify "jid" as an argument
53 then a Net::XMPP::JID object is returned and
54 you can easily parse the parts of the JID.
55 $from = $Pres->GetFrom();
57 $fromJID = $Pres->GetFrom("jid");
58 GetType() - returns the type='' attribute of the <presence/>. Each
60 presence is one of seven types:
61 available available to receive messages; default
63 unavailable unavailable to receive anything
64 subscribe ask the recipient to subscribe you
65 subscribed tell the sender they are subscribed
66 unsubscribe ask the recipient to unsubscribe you
67 unsubscribed tell the sender they are unsubscribed
68 probe probe
69 $type = $Pres->GetType();
71 GetStatus() - returns a string with the current status of the resource.
73 $status = $Pres->GetStatus();
75 GetPriority() - returns an integer with the priority of the resource
77 The default is 0 if there is no priority in this
78 presence.
79 $priority = $Pres->GetPriority();
81 GetShow() - returns a string with the state the client should show.
83 $show = $Pres->GetShow();
85 Creation functions
87 SetPresence(to=>string⎪JID - set multiple fields in the <presence/>
89 from=>string⎪JID, at one time. This is a cumulative
90 type=>string, and over writing action. If you set
91 status=>string, the "to" attribute twice, the second
92 priority=>integer, setting is what is used. If you set
93 meta=>string, the status, and then set the priority
94 icon=>string, then both will be in the <presence/>
95 show=>string, tag. For valid settings read the
96 loc=>string) specific Set functions below.
97 $Pres->SetPresence(TYPE=>"away",
99 StatuS=>"Out for lunch");
100 SetTo(string) - sets the to attribute. You can either pass a string
102 SetTo(JID) or a JID object. They must be valid JIDs or the
103 server will return an error message.
104 (ie. bob@jabber.org/Silent Bob, etc...)
105 $Pres->SetTo("bob\@jabber.org");
107 SetFrom(string) - sets the from='' attribute. You can either pass
109 SetFrom(JID) a string or a JID object. They must be valid JIDs
110 or the server will return an error message. (ie.
111 jabber:bob@jabber.org/Work) This field is not
112 required if you are writing a Client since the
113 server will put the JID of your connection in there
114 to prevent spamming.
115 $Pres->SetFrom("jojo\@jabber.org");
117 SetType(string) - sets the type attribute. Valid settings are:
119 available available to receive messages; default
121 unavailable unavailable to receive anything
122 subscribe ask the recipient to subscribe you
123 subscribed tell the sender they are subscribed
124 unsubscribe ask the recipient to unsubscribe you
125 unsubscribed tell the sender they are unsubscribed
126 probe probe
127 $Pres->SetType("unavailable");
129 SetStatus(string) - sets the status tag to be whatever string the user
131 wants associated with that resource.
132 $Pres->SetStatus("Taking a nap");
134 SetPriority(integer) - sets the priority of this resource. The highest
136 resource attached to the xmpp account is the
137 one that receives the messages.
138 $Pres->SetPriority(10);
140 SetShow(string) - sets the name of the icon or string to display for
142 this resource.
143 $Pres->SetShow("away");
145 Reply(hash) - creates a new Presence object and populates the to/from
147 fields. If you specify a hash the same as with
148 SetPresence then those values will override the Reply
149 values.
150 $Reply = $Pres->Reply();
152 $Reply = $Pres->Reply(type=>"subscribed");
153 Removal functions
155 RemoveTo() - removes the to attribute from the <presence/>.
157 $Pres->RemoveTo();
159 RemoveFrom() - removes the from attribute from the <presence/>.
161 $Pres->RemoveFrom();
163 RemoveType() - removes the type attribute from the <presence/>.
165 $Pres->RemoveType();
167 RemoveStatus() - removes the <status/> element from the <presence/>.
169 $Pres->RemoveStatus();
171 RemovePriority() - removes the <priority/> element from the
173 <presence/>.
174 $Pres->RemovePriority();
176 RemoveShow() - removes the <show/> element from the <presence/>.
178 $Pres->RemoveShow();
180 Test functions
182 DefinedTo() - returns 1 if the to attribute is defined in the
184 <presence/>, 0 otherwise.
185 $test = $Pres->DefinedTo();
187 DefinedFrom() - returns 1 if the from attribute is defined in the
189 <presence/>, 0 otherwise.
190 $test = $Pres->DefinedFrom();
192 DefinedType() - returns 1 if the type attribute is defined in the
194 <presence/>, 0 otherwise.
195 $test = $Pres->DefinedType();
197 DefinedStatus() - returns 1 if <status/> is defined in the
199 <presence/>, 0 otherwise.
200 $test = $Pres->DefinedStatus();
202 DefinedPriority() - returns 1 if <priority/> is defined in the
204 <presence/>, 0 otherwise.
205 $test = $Pres->DefinedPriority();
207 DefinedShow() - returns 1 if <show/> is defined in the <presence/>,
209 0 otherwise.
210 $test = $Pres->DefinedShow();
212
214 Ryan Eatmon
215
217 This module is free software, you can redistribute it and/or modify it
218 under the LGPL.
219perl v5.8.8 2007-04-02 Net::XMPP::Presence(3)