Asterisk developer/'s documentation 翻译计划 by serva

今天，Asterisk已经成为一个VOIP业界使用最广泛的一个集成电信级别PBX的工具，IPPBX如今已经成为VOIP商家争夺的一块重要市场，在我们越来越熟悉使用Asterisk的同时，我们希望能够越来越深入的了解asterisk，特别是对于开发人员，如果有自己特定的需求，在复杂的asterisk文件夹和asterisk的源代码文件中迷失了方向，不知所措。 在使用asterisk后，我们知道， Asterisk就是一台企业级的电话交换机，它功能的特点有:语音邮件,电话会议,呼叫路由,呼叫列队,呼叫转移,音乐保持等。然后这些功能是如何实现的，SIP和H323之间是如何进行通话的？甚至，我们也许也要问更基础一点的问题，SIP和SIP之间是如何进行通话？信令是如何控制，通话流程是怎么样?包括语音是如何进行交换传输的？这些都是我们开发人员希望了解，或者说对asterisk有不同需求的人，需要了解的。但是对于那么复杂的asterisk的代码，我们如何下手?飞云提出了对http://www.asterisk.org/doxygen/进行中文的翻译，这样可以使得有需要的人，能够初步的了解Asterisk的文件结构和文件的大概功能，可以使得更多的人参与到我们的队伍中来，一起完成对asterisk所有源码的注释。 在http://www.asterisk.org/doxygen/中，我们可以看到modules这个选项，在1.4版本中，出现了 Main文件夹，将之间版本的直接放在asterisk的根目录下的一些文件，转移到Main文件夹中，其中Main文件夹中很多文件就是对应的Main_options module。AMI functions 主要对应的源码放在manager.c文件中。此外，还有CLI_functions，CDR，Asterisk Channel Drivers，Dial plan applications 等。 对asterisk源码的重要性和规整，如下表，按照modules来放置。

--  作者：jillyyang --  发布时间：2006-10-1 22:30:00             Format 和codec的部分，由于需要的知识比较广，也比较专业，偏向于编码方面，而对于asterisk本身而言，在意的不是format或者codec本身，而是他们提供出来的接口，使得asterisk在媒体数据交换的时候，可以查到对应的编码，或者可以调用对应的压缩算法而已。所以我建议，只需要翻译有代表的几个。上面的列表中，列出来的只是.c的文件，我们翻译的时候，会对应到很多相应的.h文件，其中很多.h文件包含了大量的数据结构的定义，是对于理解asterisk非常有帮助的。 在http://www.asterisk.org/doxygen/中，file list中对应的文件，都会有Data Structures，而每个文件的Data Structures里面包含的结构，都可以Data Structures总的列表中找到Struct Reference，所以，我们在翻译的时候，以.c文件为主要翻译的对象，其中有函数的说明，程序中代码段的注释，还有其他的一些文字性的说明，然后.c文件对应的Data Structures 需要翻译到总的列表中的Struct Reference、也是归于.c文件翻译的范围之内。 此外，在http://www.asterisk.org/doxygen/中，还有Modules，Directories和Related Pages目录，Modules，Directories目录需要翻译当前页连接文件的内容。这个对于代码是相关联的。而Related Pages目录的东西，属于周围相关文档，可以参照翻译的人数来决定。 翻译只是我们熟悉的第一步，其实http://www.asterisk.org/doxygen/中，做的代码注释和介绍，是比较有限的，很多方面都没有补齐，我们的最终的目的是注释并掌握整个asterisk的源代码，便于我们自己利用。我们需要通过上面的翻译完成之后，按照翻译整理出一个asterisk的框架结构，包括，核心，扩展，以及应用等。这样可以使得，在代码注释有更多的人，真正能够入手到代码注释，这样可以保证代码注释的质量。

--  作者：jillyyang --  发布时间：2006-10-1 22:32:00 --   Main_options   asterisk.c  pbx.c  channel.c  rtp.c  file.c  config.c  sched.c  frame.c  loader.c  poll.c  say.c  io.c  dsp.c  db.c Dial plan applications  app_dial.c  app_dictate.c  app_exec.c  app_macro.c  app_echo.c  app_meetme.c  app_milliwatt.c  app_mixmonitor.c  app_queue.c  app_read.c  app_voicemail.c  app_stack.c  app_playback.c  app_queue.c  app_random.c  app_mp3.c Channel Drivers  chan_agent.c  chan_h323.c  chan_local.c  chan_sip.c  chan_zap.c  chan_features.c  chan_mgcp.c  chan_iax2.c  chan_phone.c  chan_skinny.c CDR Drivers   cdr.c  cdr_csv.c  cdr_custom.c  cdr_manager.c  cdr_tds.c  cdr_odbc.c  cdr_pgsql.c  cdr_radius.c  cdr_sqlite.c AMI functions   manager.c  astmm.c Media File Formats   format_g723.c  format_g729.c  format_h263.c  format_wav.c  format_pcm.c  format_h264.c  … Codec functions   codec_a_mu.c  codec_ulaw.c  codec_alaw.c [此贴子已经被作者于2006-10-1 22:35:38编辑过]

--  作者：jillyyang --  发布时间：2006-10-1 22:46:00 --   目前已经报名愿意参加此次行动的人有： serva：doxygen的总负责     大头：术语表总负责      书记员：amy 另外，飞云，kices，liumin，橘子香水携夫人，meng9999，wky，QQ糖；大唐盛世，肉夹馍，do-feel 因为征集人数比较多，有些没有列上，请大家跟贴或者直 接联系chinasterisk（china*）。 谢谢！ [此贴子已经被作者于2006-10-9 10:45:38编辑过]

--  作者：jillyyang --  发布时间：2006-10-9 11:11:00 --   具体分工： 模块 文件 功能 重要性 分工 Main_options   asterisk.c ASTERISK的核心执行程序， 执行着PBX的核心程序和CLI的接口程序  * 飞云  pbx.c PBX的核心程序 * 大头，篇幅较大，后期还要增加人手  channel.c channel驱动的管理和功能接口 * voipmaker&steven（原来是serva，篇幅较大，后期还要增加人手）  rtp.c rtp和rtcp协议的实现，NAT的RTP穿越的实现，转换成asterisk特有的frame形式的实现  * amy  config.c 配置文件的读取和解析，转换成对应的数据结构    file.c 通用文件读写接口，包括日志，音频文件等。    frame.c asterisk的特有的音频形式的处理    io.c I/O管理，对所有的asterisk的channel，或者是rtp做统一的管理    loader.c asteriskl的模块启动程序    app.c extension功能的调度和通用功能的接口 * meng9999  say.c asterisk报声音等的接口    sched.c asterisk的任务调度管理函数（有定时器的功能）    dsp.c 软件方式实现dsp的功能    db.c asterisk的数据库管理接口    translate.c 语音或者视频数据的codec转换程序    astmm.c asterisk内存管理程序        Dial plan  applications app_exec.c 所有的app总的执行调度程序 * liumin  app_dial.c dial函数和retrydial 函数对应的实现 * wky，篇幅较大，后期还要增加人手  app_macro.c macro函数执行和实现    app_echo.c echo 函数实现    app_meetme.c meetme会议的实现，提供函数接口给extension调用    app_mixmonitor.c MixMonitor函数，录音包括混音的功能    app_queue.c 队列的实现    app_read.c Read函数的实现，可以用来读取变量的值    app_voicemail.c 语音信箱，包括录制语音，读取语音，发送语音邮件等功能    app_stack.c Stack 应用，Gosub, Return等函数的实现    app_dictate.c Dictate函数实现，模拟指示的生成和发送    app_chanspy.c 监听所有channel语音信息的实现    app_mp3.c mp3文件播放函数的实现    app_playback.c 可以播放任何的asterisk支持的声音文件格式 * （前面有两个空格的）QQ糖  app_softhangup.c 挂机extension函数的实现    app_transfer.c extension函数，转移一路通话        Asterisk Channel  Drivers chan_sip.c SIP协议实现 * 大唐盛世，篇幅较大，后期还要增加人手  chan_h323.c H323协议的实现 * 肉夹馍  chan_local.c local的实现，asterisk在extension中独有的channel驱动程序  * kices  chan_agent.c  * leeb  chan_zap.c zaptel的应用层驱动，为zaptel的硬件调用和控制提供接口    chan_features.c     chan_mgcp.c mgcp协议实现    chan_iax2.c iax2协议实现，asterisk特有的通信协议，信令和媒体属于同一端口    chan_phone.c     chan_skinny.c         CDR Drivers   cdr.c Call Detail Record的生成程序    cdr_csv.c 文本方式的cdr    cdr_custom.c 用户化的cdr    cdr_manager.c CDR的管理程序    cdr_tds.c free tds方式的cdr    cdr_odbc.c odbc环境的cdr生成    cdr_pgsql.c pagesql方式的cdr    cdr_radius.c radius方式的cdr   * VOIP计费  cdr_sqlite.c sqlite方式的cdr        AMI functions   manager.c asterisk的管理接口 * do-feel  astman.c 经过封装的asterisk管理接口        Media File  Formats format_g723.c 723的asterisk编码实现    format_g729.c 729的asterisk编码实现    format_h263.c h263的asterisk编码实现    format_wav.c 线性的asterisk编码实现    format_pcm.c pcm的asterisk编码实现    format_h264.c h264的asterisk编码实现   Codec functions   codec_a_mu.c alaw到ulaw的编码转换实现    codec_ulaw.c ulaw的解编码    codec_alaw.c alaw的解编码   Res    functions