Adding documentation for the massive manager changes to manager
[asterisk/asterisk.git] / doc / manager_1_1.txt
1 Changes to manager version 1.1:
2 -------------------------------
3
4
5 * SYNTAX CLEANUPS
6 -----------------
7
8 - Response: headers are now either
9         "Success"       - Action OK, this message contains response
10         "Error"         - Action failed, reason in Message: header
11         "Follows"       - Action OK, response follows in following Events.
12
13 - Manager version changed to 1.1
14
15 * CHANGED EVENTS AND ACTIONS
16 ----------------------------
17 - The Hold/Unhold events
18         - Both are now "Hold" events
19                 For hold, there's a "Status: On" header, for unhold, status is off
20         - Modules chan_sip/chan_iax2
21
22 - The Ping Action
23         - Now use Response: success
24         - New header "Ping: pong" :-)
25
26 - The Events action
27         - Now use Response: Success
28         - The new status is reported as "Events: On" or "Events: Off"
29
30 - The JabberSend action
31         - The Response: header is now the first header in the response
32         - now sends "Response: Error" instead of "Failure"
33
34 - Newstate and Newchannel events
35         - these have changed headers
36         "State"         -> ChannelStateDesc     Text based channel state
37                         -> ChannelState         Numeric channel state
38         - The events does not send "<unknown>" for unknown caller IDs just an empty field
39
40 - Newchannel event
41         - Now includes "AccountCode"
42
43 - Newstate event
44         - Now has "CalleridNum" for numeric caller id, like Newchannel
45         - The event does not send "<unknown>" for unknown caller IDs just an empty field
46
47 - Dial event
48         - Event Dial has new headers, to comply with other events
49         - Source        -> Channel              Channel name (caller)
50         - SrcUniqueID   -> UniqueID             Uniqueid
51         (new)           -> Dialstring           Dialstring in app data
52
53 - Link and Unlink events
54         - The "Link" and "Unlink" bridge events in channel.c are now renamed to "Bridge"
55         - The link state is in the bridgestate: header as "Link" or "Unlink"
56         - For channel.c bridges, "Bridgetype: core" is added. This opens up for
57           bridge events in rtp.c 
58         - The RTP channel also reports Bridge: events with bridgetypes
59                 - rtp-native    RTP native bridge
60                 - rtp-direct    RTP peer-2-peer bridge (NAT support only)
61                 - rtp-remote    Remote (re-invite) bridge. (Not reported yet)
62
63 - The "Rename" manager event has a renamed header, to use the same
64         terminology for the current channel as other events
65         - Oldname       -> Channel              
66
67 - The "NewCallerID" manager event has a renamed header
68         - CallerID      -> CallerIDnum
69         - The event does not send "<unknown>" for unknown caller IDs just an empty field
70         
71 - Reload event
72         - The "Reload" event sent at manager reload now has a new header and is now implemented
73         in more modules than manager to alert a reload. For channels, there's a CHANNELRELOAD 
74         event to use.
75         (new)           -> Module: manager | CDR | DNSmgr | RTP | ENUM
76         (new)           -> Status: enabled | disabled
77         - To support reload events from other modules too
78                 - cdr module added
79
80 - Status action replies (Event: Status)
81         Header changes
82         - link          -> BridgedChannel
83         - Account       -> AccountCode
84         - (new)         -> BridgedUniqueid
85
86 - StatusComplete Event
87         New header
88         - (new)         -> Items                Number of channels reported
89         
90
91 - The ExtensionStatus manager command now has a "StatusDesc" field with text description of the state
92
93 - The Registry and Peerstatus events in chan_sip and chan_iax now use "ChannelType" instead of "ChannelDriver"
94
95 - The Response to Action: IAXpeers now have a Response: Success header
96
97 - The MeetmeJoin now has caller ID name and Caller ID number fields (like MeetMeLeave)
98
99 - Action ZapShowChannels
100         Header changes
101         - Channel:      -> ZapChannel
102         For active channels, the Channel: and Uniqueid: headers are added
103         You can now add a "ZapChannel: " argument to zapshowchannels actions
104         to only get information about one channel.
105
106 - Event ZapShowChannelsComplete
107         New header
108         - (new)         -> Items:       Reports number of channels reported
109
110 * NEW ACTIONS
111 -------------
112 - Action: ModuleLoad
113         Modules: loader.c
114         Purpose:
115                 To be able to unload, reload and unload modules from AMI.
116         Variables: 
117           ActionID: <id>          Action ID for this transaction. Will be returned.
118           Module: <name>          Asterisk module name (including .so extension)
119                                   or subsystem identifier:
120                                 cdr, enum, dnsmgr, extconfig, manager, rtp, http
121           LoadType: load | unload | reload
122                           The operation to be done on module
123         If no module is specified for a reload loadtype, all modules are reloaded
124
125 - Action: ModuleCheck
126         Modules: loader.c
127         Purpose:
128                 To check version of a module - if it's loaded
129         Variables:
130           ActionID: <id>          Action ID for this transaction. Will be returned.
131           Module: <name>          Asterisk module name (not including extension)
132         Returns:
133                 If module is loaded, returns version number of the module
134                 
135                 Note: This will have to change. I don't like sending Response: failure
136                 on both command not found (trying this command in earlier versions of
137                 Asterisk) and module not found.
138                 Also, check if other manager actions behave that way.
139
140 * NEW EVENTS
141 ------------
142
143 - Event: Transfer
144         Modules: res_features, chan_sip
145         Purpose:
146                 Inform about call transfer, linking transferer with transfer target
147                 You should be able to trace the call flow with this missing piece
148                 of information. If it works out well, the "Transfer" event should
149                 be followed by a "Bridge" event
150                 The transfermethod: header informs if this is a pbx core transfer
151                 or something done on channel driver level. For SIP, check the example:
152         Example:
153                 
154                 Event: Transfer
155                 Privilege: call,all
156                 TransferMethod: SIP
157                 TransferType: Blind
158                 Channel: SIP/device1-01849800
159                 SIP-Callid: 091386f505842c87016c4d93195ec67d@127.0.0.1
160                 TargetChannel: SIP/device2-01841200
161                 TransferExten: 100
162                 TransferContext: default
163
164 - Event: ChannelUpdate
165         Modules: chan_sip.c, chan_iax2.c
166         Purpose:
167                 Updates channel information with ID of PVT in channel driver, to
168                 be able to link events on channel driver level.
169                 * Integrated in SVN trunk as of May 4th, 2007
170
171         Example:
172
173                 Event: ChannelUpdate
174                 Privilege: system,all
175                 Uniqueid: 1177271625.27
176                 Channel: SIP/olle-01843c00
177                 Channeltype: SIP
178                 SIPcallid: NTQzYWFiOWM4NmE0MWRkZjExMzU2YzQ3OWQwNzg3ZmI.
179                 SIPfullcontact: sip:olle@127.0.0.1:49054
180
181 - Action: CoreSettings
182         Modules: manager.c
183         Purpose: To report core settings, like AMI and Asterisk version,
184                 maxcalls and maxload settings.
185                 * Integrated in SVN trunk as of May 4th, 2007
186         Example:
187                 Response: Success
188                 ActionID: 1681692777
189                 AMIversion: 1.1
190                 AsteriskVersion: SVN-oej-moremanager-r61756M
191                 SystemName: EDVINA-node-a
192                 CoreMaxCalls: 120
193                 CoreMaxLoadAvg: 0.000000
194                 CoreRunUser: edvina
195                 CoreRunGroup: edvina
196
197 - Action: CoreStatus
198         Modules: manager.c
199         Purpose: To report current PBX core status flags, like
200                 number of concurrent calls, startup and reload time.
201                 * Integrated in SVN trunk as of May 4th, 2007
202         Example:
203                 Response: Success
204                 ActionID: 1649760492
205                 CoreStartupTime: 22:35:17
206                 CoreReloadTime: 22:35:17
207                 CoreCurrentCalls: 20
208
209 - Event: NewAccountCode
210         Modules: cdr.c
211         Purpose: To report a change in account code for a live channel
212         Example:
213                 Event: NewAccountCode
214                 Privilege: call,all
215                 Channel: SIP/olle-01844600
216                 Uniqueid: 1177530895.2
217                 AccountCode: Stinas account 1234848484
218                 OldAccountCode: OllesAccount 12345
219
220 - Event: ModuleLoadReport
221         Modules: loader.c
222         Purpose: To report that module loading is complete. Some aggressive
223                 clients connect very quickly to AMI and needs to know when
224                 all manager events embedded in modules are loaded
225                 Also, if this does not happen, something is seriously wrong.
226                 This could happen to chan_sip and other modules using DNS.
227         Example:
228                 Event: ModuleLoad
229                 ModuleLoadStatus: Done
230                 ModuleSelection: All
231                 ModuleCount: 24
232                 
233
234 * TODO
235 ------
236