Wed Jan 8 2020 09:50:22

Asterisk developer's documentation


Todo List
Global __ast_read (struct ast_channel *chan, int dropaudio)
XXX It is possible to write a digit to the audiohook twice if the digit was originally read while the channel was in autoservice.
Global __sip_reliable_xmit (struct sip_pvt *p, uint32_t seqno, int resp, struct ast_str *data, int fatal, int sipmethod)
According to the RFC some packets need to be retransmitted even if its TCP, so this needs to get revisited
Global add_peer_mailboxes (struct sip_peer *peer, const char *value)
document this function
File ael_structs.h
document this file (ael.h)
Class ao2_container
Linking and unlink objects is typically expensive, as it involves a malloc() of a small object which is very inefficient. To optimize this, we allocate larger arrays of bucket_entry's when we run out of them, and then manage our own freelist. This will be more efficient as we can do the freelist management while we hold the lock (that we need anyways).
File app_originate.c
Make a way to be able to set variables (and functions) on the outbound channel, similar to the Variable headers for the AMI Originate, and the Set options for call files.
Global ast_audiohook_move_by_source (struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source)
Currently only the first audiohook of a specific source found will be moved. We should add the capability to move multiple audiohooks from a single source as well.
Global ast_bridge_call (struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config)
XXX how do we guarantee the latter ?
Global ast_cel_fabricate_channel_from_event (const struct ast_event *event)
This function is very expensive, especially given that some CEL backends use it on every CEL event. This function really needs to go away at some point.
Global ast_channel_connected_line_macro (struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const void *connected_info, int caller, int frame)

Have multiple return codes based on the MACRO_RESULT

Make constants so that caller and frame can be more expressive than just '1' and '0'

Global ast_channel_connected_line_macro (struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const void *connected_info, int caller, int frame)

Have multiple return codes based on the MACRO_RESULT

Make constants so that caller and frame can be more expressive than just '1' and '0'

Global ast_channel_redirecting_macro (struct ast_channel *autoservice_chan, struct ast_channel *macro_chan, const void *redirecting_info, int is_caller, int is_frame)

Have multiple return codes based on the MACRO_RESULT

Make constants so that caller and frame can be more expressive than just '1' and '0'

File ast_expr.h
Explain this file!
Class ast_generator
Add an explanation of an Asterisk generator
Class ast_party_caller
Implement settings for transliteration between UTF8 Caller ID names in to ASCII Caller ID's (DAHDI). Östen Åsklund might be transliterated into Osten Asklund or Oesten Aasklund depending upon language and person... We need automatic routines for incoming calls and static settings for our own accounts.
Global ast_party_name::char_set
Start using the party name character set value. Not currently used.
Global ast_rtcp_calc_interval (struct ast_rtp *rtp)
XXX Do a more reasonable calculation on this one Look in RFC 3550 Section A.7 for an example
Global ast_security_event_severity
Do we need any more levels here?
Global ast_write (struct ast_channel *chan, struct ast_frame *frame)
XXX should return 0 maybe ?
Global ast_write (struct ast_channel *chan, struct ast_frame *frame)
XXX should return 0 maybe ?
Page Asterisk API
Link to wiki content
Page Asterisk Language Syntaxes supported
Note that in future, we need to move to a model where we can differentiate further - e.g. between en_US & en_UK
File bridge_softmix.c
This bridge operates in 8 kHz mode unless a define is uncommented. This needs to be improved so the bridge moves between the dominant codec as needed depending on channels present in the bridge and transcoding capabilities.
Class bucket_entry
this should be private to the container code
Global BUF_SIZE
Check this buf size estimate, it may be totally wrong for large frame video
File cel.c
Do thorough testing of all transfer methods to ensure that BLINDTRANSFER, ATTENDEDTRANSFER, BRIDGE_START, and BRIDGE_END events are all reported as expected.
File chan_dahdi.c
Deprecate the "musiconhold" configuration option post 1.4
File chan_gtalk.c

Support config reloading.

Fix native bridging.

File chan_iax2.c
Implement musicclass settings for IAX2 devices
File chan_sip.c

Better support of forking

VIA branch tag transaction checking

Transaction support

Global check_auth (struct sip_pvt *p, struct sip_request *req, const char *username, const char *secret, const char *md5secret, int sipmethod, const char *uri, enum xmittype reliable, int ignore)

need a better return code here

need a better return code here

need a better return code here

Global check_rtp_timeout (struct sip_pvt *dialog, time_t t)
Check video RTP keepalives
Global create_addr (struct sip_pvt *dialog, const char *opeer, struct ast_sockaddr *addr, int newdialog)
Fix this function. When we ask for SRV, we should check all transports In the future, we should first check NAPTR to find out transport preference
Global dahdi_answer (struct ast_channel *ast)
XXX this is redundantly set by the analog and PRI submodules!
Global dahdi_setoption (struct ast_channel *chan, int option, void *data, int datalen)
XXX This is an abuse of the stack!!
File devicestate.h
Currently, when the state of a device changes, the device state provider calls one of the functions defined here to queue an object to say that the state of a device has changed. However, this does not include the new state. Another thread processes these device state change objects and calls the device state provider's callback to figure out what the new state is. It would make a lot more sense for the new state to be included in the original function call that says the state of a device has changed. However, it will take a lot of work to change this.
Global dialog_needdestroy (void *dialogobj, void *arg, int flags)
Re-work this to improve efficiency. Currently, this function is called on every dialog after processing every incoming SIP/UDP packet, or potentially even more often when the scheduler has entries to run.
Global do_forward (struct chanlist *o, struct cause_args *num, struct ast_flags64 *peerflags, int single, int caller_entertained, int *to, struct ast_party_id *forced_clid, struct ast_party_id *stored_clid)
eventually this function should be intergrated into and replaced by ast_call_forward()
File enum.c

Implement a caching mechanism for multile enum lookups

The service type selection needs to be redone.

Global feature_exec_app (struct ast_channel *chan, struct ast_channel *peer, struct ast_bridge_config *config, const char *code, int sense, void *data)
XXX should probably return res
File func_devstate.c
Delete the entry from AstDB when set to nothing like Set(DEVICE_STATE(Custom:lamp1)=)
Global function_sippeer (struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
Will be deprecated after 1.4
Global get_transport_pvt (struct sip_pvt *p)
Fix this function to work correctly
Global gtalk_parser (void *data, ikspak *pak)
XXX TODO make this work.
Global handle_redirect (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
It would be nice to be able to redirect 2 channels at the same time like you can with AMI redirect. However, it is not possible to acquire two channels without the potential for a deadlock with how ast_channel structs are managed today. Once ast_channel is a refcounted object, this command will be able to support that.
Global handle_request_invite (struct sip_pvt *p, struct sip_request *req, int debug, uint32_t seqno, struct ast_sockaddr *addr, int *recount, const char *e, int *nounlock)
XXX This needs to be reviewed. YOu don't change the request URI really, you route the packet correctly instead...
Global handle_show_settings (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
we could check musiconhold, voicemail, smdi, adsi, queues
Global initreqprep (struct sip_request *req, struct sip_pvt *p, int sipmethod, const char *const explicit_uri)
Need to add back the VXML URL here at some point, possibly use build_string for all this junk
Global JABBER_CONFIG
This should really be renamed to xmpp.conf. For backwards compatibility, we need to read both files
Global load_module (void)
Leaking anything allocated by reload_config() ...
Global MAX_CHANLIST_LEN
Move definition of MAX_CHANLIST_LEN to a proper place.
Global mgcp_subchannel::cxident [80]
FIXME txident is replaced by rqnt_ident in endpoint. This should be obsoleted
Global parking_con_dial []
Might be able to eliminate the parking_con_dial context kludge by running app_dial directly in its own thread to simulate a PBX.
Global parse_moved_contact (struct sip_pvt *p, struct sip_request *req, char **name, char **number, int set_call_forward)
XXX Doesn't redirect over TLS on sips: uri's. If we get a redirect to a SIPS: uri, this needs to be going back to the dialplan (this is a request for a secure signalling path). Note that transport=tls is deprecated, but we need to support it on incoming requests.
Global parse_register_contact (struct sip_pvt *pvt, struct sip_peer *peer, struct sip_request *req)
Check NAPTR/SRV if we have not got a port in the URI
Global pbx_builtin_importvar (struct ast_channel *, const char *)
XXX should do !ast_strlen_zero(..) of the args ?
Global peer_iphash_cb (const void *obj, const int flags)
Find a better hashing function
Global powerof (format_t d)
TODO: sample frames for each supported input format. We build this on the fly, by taking an SLIN frame and using the existing converter to play with it.
File res_adsi.c

Move app_getcpeid into this module

Create a core layer so that app_voicemail does not require res_adsi to load

File res_agi.c
Convert the rest of the AGI commands over to XML documentation
File res_calendar.c

Support responding to a meeting invite

Support writing attendees

File res_jabber.c

If you unload this module, chan_gtalk/jingle will be dead. How do we handle that?

Dialplan applications need RETURN variable, like JABBERSENDSTATUS

File res_security_log.c

Make informational security events optional

Escape quotes in string payload IE contents

File res_smdi.c
This module currently has its own mailbox monitoring thread. This should be converted to MWI subscriptions and just let the optional global voicemail polling thread handle it.
Global SAMPLE_RATE
Make this optional. If this is only going to talk to 8 kHz endpoints, then it makes sense to use 8 kHz natively.
Global SAY_INIT (x)
XXX As the conversion from the old implementation of say.c to the new implementation will be completed, and the API suitably reworked by removing redundant functions and/or arguments, this mechanism may be reverted back to pure static functions, if needed.
Global scan_service (const char *fn, time_t now)
XXX There is some odd delayed duplicate servicing of call files going on. We need to suppress the error message if the file does not exist as a result.
Global set_address_from_contact (struct sip_pvt *pvt)
We need to save the TRANSPORT here too
Global set_destination (struct sip_pvt *p, char *uri)

XXX If we have sip_cfg.srvlookup on, then look for NAPTR/SRV, otherwise, just look for A records

XXX If we have sip_cfg.srvlookup on, then look for NAPTR/SRV, otherwise, just look for A records

XXX If we have sip_cfg.srvlookup on, then look for NAPTR/SRV, otherwise, just look for A records

Global sig_pri_handle_subcmds (struct sig_pri_span *pri, int chanpos, int event_id, int channel, const struct pri_subcommands *subcmds, q931_call *call_rsp)
XXX Original called data can be put in a channel data store that is inherited.
Global sig_pri_redirecting_update (struct sig_pri_chan *pvt, struct ast_channel *ast)
XXX Original called data can be put in a channel data store that is inherited.
Page SIP TCP and TLS support

Fix TCP/TLS handling in dialplan, SRV records, transfers and much more

Save TCP/TLS sessions in registry If someone registers a SIPS uri, this forces us to set up a TLS connection back.

Add TCP/TLS information to function SIPPEER and SIPCHANINFO

If tcpenable=yes, we must open a TCP socket on the same address as the IP for UDP. The tcpbindaddr config option should only be used to open ADDITIONAL ports So we should propably go back to bindaddr= the default address to bind to. If tcpenable=yes, then bind this to both udp and TCP if tlsenable=yes, open TLS port (provided we also have cert) tcpbindaddr = extra address for additional TCP connections tlsbindaddr = extra address for additional TCP/TLS connections udpbindaddr = extra address for additional UDP connections These three options should take multiple IP/port pairs Note: Since opening additional listen sockets is a new feature we do not have today the XXXbindaddr options needs to be disabled until we have support for it

We need to test TCP sessions with SIP proxies and in regards to the SIP outbound specs.

;transport=tls was deprecated in RFC3261 and should not be used at all. See section 26.2.2.

Since we have had multidomain support in Asterisk for quite a while, we need to support multiple domains in our TLS implementation, meaning one socket and one cert per domain

Selection of transport for a request needs to be done after we've parsed all route headers, also considering outbound proxy options. First request: Outboundproxy, routes, (reg contact or URI. If URI doesn't have port: DNS naptr, srv, AAA) Intermediate requests: Outboundproxy(only when forced), routes, contact/uri DNS naptr support is crucial. A SIP uri might lead to a TLS connection. Also note that due to outbound proxy settings, a SIPS uri might have to be sent on UDP (not to recommend though)

Default transports are set to UDP, which cause the wrong behaviour when contacting remote devices directly from the dialplan. UDP is only a fallback if no other method works, in order to be compatible with RFC2543 (SIP/1.0) devices. For transactions that exceed the MTU (like INIVTE with video, audio and RTT) TCP should be preferred.

re-evaluate the transport= setting in sip.conf. This is right now not well thought of. If a device in sip.conf contacts us via TCP, we should not switch transport, even if udp is the configured first transport.

Be prepared for one outbound and another incoming socket per pvt. This applies specially to communication with other peers (proxies).

If the message is smaller than the given Content-length, the request should get a 400 Bad request message. If it's a response, it should be dropped. (RFC 3261, Section 18.3)

Global sip_prepare_socket (struct sip_pvt *p)

Get socket for dialog, prepare if needed, and return file handle

Check this... This might be wrong, depending on the proxy configuration If proxy is in "force" mode its correct.

Check this... This might be wrong, depending on the proxy configuration If proxy is in "force" mode its correct.

Global sip_prune_realtime (struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)
XXXX Propably needs an overhaul after removal of the devices
Global sip_sipredirect (struct sip_pvt *p, const char *dest)
Fix this function so that we wait for reply to the REFER and react to errors, denials or other issues the other end might have.
Global tdd_gen_holdtone (unsigned char *outbuf)
How big should this be???
Global tdd_gen_holdtone (unsigned char *outbuf)
How big should this be???
Global terminate_uri (char *uri)
As this function does not support user-parameters, it's considered broken and needs fixing.
Global transmit_refer (struct sip_pvt *p, const char *dest)

Fix the transfer() dialplan function so that a transfer may fail

In theory, we should hang around and wait for a reply, before returning to the dial plan here. Don't know really how that would affect the transfer() app or the pbx, but, well, to make this useful we should have a STATUS code on transfer().

In theory, we should hang around and wait for a reply, before returning to the dial plan here. Don't know really how that would affect the transfer() app or the pbx, but, well, to make this useful we should have a STATUS code on transfer().

File udptl.h
add doxygen documentation to this file!
Class unistim_line
Convert to stringfields
Global unload_module (void)
XXX TODO make this work.
Global wait_for_answer (struct queue_ent *qe, struct callattempt *outgoing, int *to, char *digit, int prebusies, int caller_disconnect, int forwardsallowed, int ringing)
eventually all call forward logic should be intergerated into and replaced by ast_call_forward()