1Net::XMPP::Client(3) User Contributed Perl Documentation Net::XMPP::Client(3)
2
6 Net::XMPP::Client - XMPP Client Module
7
9 Net::XMPP::Client is a module that provides a developer easy access to
10 the Extensible Messaging and Presence Protocol (XMPP).
11
13 Client.pm uses Protocol.pm to provide enough high level APIs and
14 automation of the low level APIs that writing an XMPP Client in Perl is
15 trivial. For those that wish to work with the low level you can do
16 that too, but those functions are covered in the documentation for each
17 module.
18 Net::XMPP::Client provides functions to connect to an XMPP server,
20 login, send and receive messages, set personal information, create a
21 new user account, manage the roster, and disconnect. You can use all
22 or none of the functions, there is no requirement.
23 For more information on how the details for how Net::XMPP is written
25 please see the help for Net::XMPP itself.
26 For a full list of high level functions available please see
28 Net::XMPP::Protocol.
29 Basic Functions
31 use Net::XMPP;
32 $Con = Net::XMPP::Client->new();
34 $Con->SetCallbacks(...);
36 $Con->Execute(hostname=>"jabber.org",
38 username=>"bob",
39 password=>"XXXX",
40 resource=>"Work"
41 );
42 For the list of available functions see Net::XMPP::Protocol.
44 $Con->Disconnect();
46
49 new
50 new(debuglevel=>0|1|2,
51 debugfile=>string,
52 debugtime=>0|1)
53 creates the Client object. debugfile should be set to the path for the
55 debug log to be written. If set to "stdout" then the debug will go
56 there. debuglevel controls the amount of debug. For more information
57 about the valid setting for debuglevel, debugfile, and debugtime see
58 Net::XMPP::Debug.
59 Connect
61 Connect(hostname=>string,
62 port=>integer,
63 timeout=>int,
64 connectiontype=>string,
65 tls=>0|1,
66 srv=>0|1,
67 componentname=>string)
68 opens a connection to the server listed in the hostname (default
70 localhost), on the port (default 5222) listed, using the connectiontype
71 listed (default tcpip). The two connection types available are:
72 tcpip standard TCP socket
74 http TCP socket, but with the
75 headers needed to talk
76 through a web proxy
77 If you specify tls, then it TLS will be used if it is available as a
79 feature.
80 If srv is specified AND Net::DNS is installed and can be loaded, then
82 an SRV query is sent to srv.hostname and the results processed to
83 replace the hostname and port. If the lookup fails, or Net::DNS cannot
84 be loaded, then hostname and port are left alone as the defaults.
85 Alternatively, you may manually specify componentname as the domain
87 portion of the jid and leave hostname set to the actual hostname of the
88 XMPP server.
89 Execute
91 Execute(hostname=>string,
92 port=>int,
93 tls=>0|1,
94 username=>string,
95 password=>string,
96 resource=>string,
97 register=>0|1,
98 connectiontype=>string,
99 connecttimeout=>string,
100 connectattempts=>int,
101 connectsleep=>int,
102 processtimeout=>int)
103 Generic inner loop to handle connecting to the server, calling Process,
105 and reconnecting if the connection is lost. There are five callbacks
106 available that are called at various places:
107 onconnect - when the client has
109 made a connection.
110 onauth - when the connection is
112 made and user has been
113 authed. Essentially,
114 this is when you can
115 start doing things
116 as a Client. Like
117 send presence, get your
118 roster, etc...
119 onprocess - this is the most
121 inner loop and so
122 gets called the most.
123 Be very very careful
124 what you put here
125 since it can
126 *DRASTICALLY* affect
127 performance.
128 ondisconnect - when the client
130 disconnects from
131 the server.
132 onexit - when the function gives
134 up trying to connect and
135 exits.
136 The arguments are passed straight on to the Connect function, except
138 for connectattempts and connectsleep. connectattempts is the number of
139 times that the Component should try to connect before giving up. -1
140 means try forever. The default is -1. connectsleep is the number of
141 seconds to sleep between each connection attempt.
142 If you specify register=>1, then the Client will attempt to register
144 the sepecified account for you, if it does not exist.
145 Process
147 Process(integer)
148 takes the timeout period as an argument. If no timeout is listed then
150 the function blocks until a packet is received. Otherwise it waits
151 that number of seconds and then exits so your program can continue
152 doing useful things. NOTE: This is important for GUIs. You need to
153 leave time to process GUI commands even if you are waiting for packets.
154 The following are the possible return values, and what they mean:
155 1 - Status ok, data received.
157 0 - Status ok, no data received.
158 undef - Status not ok, stop processing.
159 IMPORTANT: You need to check the output of every Process. If you get
161 an undef then the connection died and you should behave accordingly.
162 Disconnect
164 Disconnect()
165 closes the connection to the server.
167 Connected
169 Connected()
170 returns 1 if the Transport is connected to the server, and 0 if not.
172
174 Originally authored by Ryan Eatmon.
175 Previously maintained by Eric Hacker.
177 Currently maintained by Darian Anthony Patrick.
179
181 This module is free software, you can redistribute it and/or modify it
182 under the LGPL 2.1.
183perl v5.34.0 2022-01-21 Net::XMPP::Client(3)