1Net::XMPP::Presence(3)User Contributed Perl DocumentationNet::XMPP::Presence(3)
2
3
4

NAME

6       Net::XMPP::Presence - XMPP Presence Module
7

SYNOPSIS

9       Net::XMPP::Presence is a companion to the Net::XMPP module.  It
10       provides the user a simple interface to set and retrieve all parts of
11       an XMPP Presence.
12

DESCRIPTION

14       A Net::XMPP::Presence object is passed to the callback function for the
15       message.  Also, the first argument to the callback functions is the
16       session ID from XML::Streams.  There are some cases where you might
17       want this information, like if you created a Client that connects to
18       two servers at once, or for writing a mini server.
19
20           use Net::XMPP;
21
22           sub presence {
23             my ($sid,$Pres) = @_;
24             .
25             .
26             .
27           }
28
29       You now have access to all of the retrieval functions available.
30
31       To create a new presence to send to the server:
32
33           use Net::XMPP;
34
35           $Pres = Net::XMPP::Presence->new();
36
37       Now you can call the creation functions below to populate the tag
38       before sending it.
39

METHODS

41   Retrieval functions
42       GetTo
43             GetTo()
44
45           returns the value in the to='' attribute for the <presence/>.
46
47             GetTo("jid")
48
49           If you specify "jid" as an argument then a Net::XMPP::JID object is
50           returned and you can easily parse the parts of the JID.
51
52             $to    = $Pres->GetTo();
53             $toJID = $Pres->GetTo("jid");
54
55       GetFrom
56             GetFrom()
57
58           returns the value in the from='' attribute for the <presence/>.
59
60             GetFrom("jid")
61
62           If you specify "jid" as an argument then a Net::XMPP::JID object is
63           returned and you can easily parse the parts of the JID.
64
65             $from    = $Pres->GetFrom();
66             $fromJID = $Pres->GetFrom("jid");
67
68       GetType
69             GetType()
70
71           returns the type='' attribute of the <presence/>.  Each presence is
72           one of seven types:
73
74             available       available to receive messages; default
75             unavailable     unavailable to receive anything
76             subscribe       ask the recipient to subscribe you
77             subscribed      tell the sender they are subscribed
78             unsubscribe     ask the recipient to unsubscribe you
79             unsubscribed    tell the sender they are unsubscribed
80             probe           probe
81
82             $type = $Pres->GetType();
83
84       GetStatus
85             GetStatus()
86
87           returns a string with the current status of the resource.
88
89             $status = $Pres->GetStatus();
90
91       GetPriority
92             GetPriority()
93
94           returns an integer with the priority of the resource The default is
95           0 if there is no priority in this presence.
96
97             $priority = $Pres->GetPriority();
98
99       GetShow
100             GetShow()
101
102           Returns a string with the state the client should show.
103
104             $show = $Pres->GetShow();
105
106   Creation functions
107       SetPresence
108             SetPresence(to=>string|JID
109                         from=>string|JID,
110                         type=>string,
111                         status=>string,
112                         priority=>integer,
113                         meta=>string,
114                         icon=>string,
115                         show=>string,
116                         loc=>string)
117
118           set multiple fields in the <presence/> at one time.  This is a
119           cumulative and over writing action.  If you set the "to" attribute
120           twice, the second setting is what is used.  If you set the status,
121           and then set the priority then both will be in the <presence/> tag.
122           For valid settings read the specific Set functions below.
123
124             $Pres->SetPresence(TYPE=>"away", StatuS=>"Out for lunch");
125
126       SetTo
127             SetTo(string)
128             SetTo(JID)
129
130           sets the to attribute.  You can either pass a string or a JID
131           object.  They must be valid JIDs or the server will return an error
132           message.  (ie.  bob@jabber.org/Silent Bob, etc...)
133
134             $Pres->SetTo("bob\@jabber.org");
135
136       SetFrom
137             SetFrom(string)
138
139           sets the from='' attribute.  You can either pass
140
141             SetFrom(JID)
142
143           A string or a JID object.  They must be valid JIDs or the server
144           will return an error message. (ie.  jabber:bob@jabber.org/Work)
145           This field is not required if you are writing a Client since the
146           server will put the JID of your connection in there to prevent
147           spamming.
148
149             $Pres->SetFrom("jojo\@jabber.org");
150
151       SetType
152             SetType(string)
153
154           sets the type attribute.  Valid settings are:
155
156             available      available to receive messages; default
157             unavailable    unavailable to receive anything
158             subscribe      ask the recipient to subscribe you
159             subscribed     tell the sender they are subscribed
160             unsubscribe    ask the recipient to unsubscribe you
161             unsubscribed   tell the sender they are unsubscribed
162             probe          probe
163
164             $Pres->SetType("unavailable");
165
166       SetStatus
167             SetStatus(string)
168
169           sets the status tag to be whatever string the user wants associated
170           with that resource.
171
172             $Pres->SetStatus("Taking a nap");
173
174       SetPriority
175             SetPriority(integer)
176
177           sets the priority of this resource.  The highest resource attached
178           to the xmpp account is the one that receives the messages.
179
180             $Pres->SetPriority(10);
181
182       SetShow
183             SetShow(string)
184
185           Sets the name of the icon or string to display for this resource.
186
187             $Pres->SetShow("away");
188
189       Reply
190             Reply(hash)
191
192           creates a new Presence object and populates the to/from fields.  If
193           you specify a hash the same as with SetPresence then those values
194           will override the Reply values.
195
196             $Reply = $Pres->Reply();
197             $Reply = $Pres->Reply(type=>"subscribed");
198
199   Removal functions
200       RemoveTo
201           removes the to attribute from the <presence/>.
202
203             $Pres->RemoveTo();
204
205       RemoveFrom
206           removes the from attribute from the <presence/>.
207
208            $Pres->RemoveFrom();
209
210       RemoveType
211           removes the type attribute from the <presence/>.
212
213            $Pres->RemoveType();
214
215       RemoveStatus
216           removes the <status/> element from the <presence/>.
217
218            $Pres->RemoveStatus();
219
220       RemovePriority
221           removes the <priority/> element from the <presence/>.
222
223            $Pres->RemovePriority();
224
225       RemoveShow
226           removes the <show/> element from the <presence/>.
227
228             $Pres->RemoveShow();
229
230   Test functions
231       DefinedTo
232           returns 1 if the to attribute is defined in the <presence/>, 0
233           otherwise.
234
235             $test = $Pres->DefinedTo();
236
237       DefinedFrom
238           returns 1 if the from attribute is defined in the <presence/>, 0
239           otherwise.
240
241            $test = $Pres->DefinedFrom();
242
243       DefinedType
244           returns 1 if the type attribute is defined in the <presence/>, 0
245           otherwise.
246
247             $test = $Pres->DefinedType();
248
249       DefinedStatus
250           returns 1 if <status/> is defined in the <presence/>, 0 otherwise.
251
252             $test = $Pres->DefinedStatus();
253
254       DefinedPriority
255           returns 1 if <priority/> is defined in the <presence/>, 0
256           otherwise.
257
258             $test = $Pres->DefinedPriority();
259
260       DefinedShow
261           returns 1 if <show/> is defined in the <presence/>, 0 otherwise.
262
263             $test = $Pres->DefinedShow();
264

AUTHOR

266       Originally authored by Ryan Eatmon.
267
268       Previously maintained by Eric Hacker.
269
270       Currently maintained by Darian Anthony Patrick.
271

COPYRIGHT

273       This module is free software, you can redistribute it and/or modify it
274       under the LGPL 2.1.
275
276
277
278perl v5.36.0                      2023-01-20            Net::XMPP::Presence(3)