siproc

git clone git://xatko.vsos.ethz.ch/siproc.git
Log | Files | Refs | README | LICENSE

siproc.1 (6265B)


      1 .TH siproc 1 "2019-11-16" "0.1.0" "siproc man page"
      2 .
      3 .SH NAME
      4 siproc \- a SIP softphone spawning processes for calls
      5 .
      6 .SH SYNOPSIS
      7 .SY
      8 siproc
      9 .I /path/to/executable
     10 .RI [ args \&...]
     11 .YS
     12 .
     13 .SH DESCRIPTION
     14 siproc is a SIP client, that spawns the process given by
     15 .I /path/to/executable
     16 for every incoming or outgoing call, passing it the command line parameters
     17 .IR args .
     18 .PP
     19 Using standard input and output, these processes can exchange commands and events
     20 with the parent process, that allow interaction with the caller/callee.
     21 These command allow the program to answering calls, play files, send and receive
     22 DTMF Tones et cetera.
     23 On remote hangup, the child process is killed via SIGTERM.
     24 .
     25 .PP
     26 The account settings and other configuration are read via environment variables.
     27 .
     28 .SH EXIT STATUS
     29 .IP 0
     30 on normal termination
     31 .IP 1
     32 on program or configuration error (check standard error for details)
     33 .SH ENVIRONMENT
     34 Configuration parameters are given via environment variables
     35 .TP
     36 .B SIPROC_REGISTRAR_URI
     37 The server siproc should connect to, as a SIP URI (e.g "sip:myserver.tld")
     38 .TP
     39 .B SIPROC_ID_URI
     40 The ID URI of the account used, e.g. "Full Name <sip:Account@myserver.lan>"
     41 .TP
     42 .B SIPROC_USERNAME
     43 The username of the account
     44 .TP
     45 .B SIPROC_USERNAME
     46 The password of the account
     47 .TP
     48 .B SIPROC_TRANSPORT_PORT
     49 The port used by siproc. This variable is optional, and defaults to 5060.
     50 If you want to run multiple instances of siproc on the same machine, set
     51 it to distinct values, since the softphone binds to it.
     52 .TP
     53 .B SIPROC_LOG_LEVEL
     54 The verbosity of the pjsua-library. Smaller values yield less noise on stdout.
     55 .TP
     56 .B SIPROC_CODEC_PRIORITIES
     57 Set the priorities of different codecs used by pjsua.
     58 It must be of the form 
     59 .B <name>:<prio>[,<name>:<prio>...]
     60 Setting the priority to 0 disables the codec.
     61 For a list of all available codecs, refer to the output of 
     62 .B siproc-parameters
     63 .
     64 .SS SUBPROCESS ENVIRONMENT VARIABLES
     65 The processes spawned by siproc are passed the following environment variables:
     66 .TP
     67 .B SIPROC_REMOTE_URI
     68 The SIP URI of the remote end
     69 .TP
     70 .B SIPROC_REMOTE_ID
     71 Some pjsip interna, look it up in their documentation of the struct CallInfo
     72 .TP
     73 .B SIPROC_REMOTE_CONTACT
     74 Some pjsip interna, look it up in their documentation of the struct CallInfo
     75 .TP
     76 .B SIPROC_OUTGOING
     77 Whether the call being handled by this process is an incoming call (="n") or an
     78 outgoing call (="y")
     79 .
     80 .SH PROCESS COMMANDS AND EVENTS
     81 This section will explain the communication protocol between the main process and
     82 its children, as well as the commands the main process can be given on its standard
     83 input.
     84 .PP
     85 Make sure that the pipes are flushed after writing to them, otherwise the commands
     86 will not get extecuted.
     87 .
     88 .SS MAIN PROGRAM COMMANDS
     89 The main program reads some commands on standard input, terminated by newlines ('\\n'):
     90 .TP
     91 .B QUIT
     92 Terminates the program, disconnecting all calls.
     93 .TP
     94 .B CALL [SIP URI]
     95 Call a number, with
     96 .B SIP URI
     97 the address to be called, e.g. sip:contact@remote.tld
     98 .
     99 .SS SUBPROCESS COMMANDS
    100 The spawned child process can give commands via stdout and read events via stdin.
    101 Each command or event is separated by a newline ('\\n').
    102 The following commands are supported:
    103 .TP
    104 .B RINGING
    105 Let's the remote end know that we are ringing.
    106 .TP
    107 .B ANSWER
    108 Answer an incoming call
    109 .TP
    110 .B HANGUP
    111 Hang up a call
    112 .TP
    113 .B TRANSFER [URI]
    114 Redirect a call to an URI of the form sip:contact@remote
    115 .TP
    116 .B DTMF [STRING]
    117 Dial the DTMF tones of each character in 
    118 .B STRING
    119 .TP
    120 .B PLAY [FILE]
    121 Play a file from a given path, relative to the current working directory of the
    122 main siproc process. Multiple files can be played at the same time.
    123 .TP
    124 .B STOP
    125 Stop the file that has been added last.
    126 .TP
    127 .B MESSAGE [STRING]
    128 Send a SIP message to the remote side
    129 .TP
    130 .B RECORD [FILE]
    131 Record the conversation to the given file. If no file is given, the current
    132 recording is stopped.
    133 .TP
    134 .B APLAY [DEVICE]
    135 Play the stream of the alsa-device 
    136 .B DEVICE
    137 to the remote end.
    138 See the output of the
    139 .B siproc-parameters
    140 utility for all available device strings
    141 .TP
    142 .B ARECORD [DEVICE]
    143 Play the audio stream from the remote end into the alsa device
    144 .BR DEVICE .
    145 See the output of the
    146 .B siproc-parameters
    147 utility for all available device strings
    148 .TP
    149 .B ASTOP [DEVICE]
    150 Stop both playing the remote end into and the local stream from
    151 .BR DEVICE .
    152 .
    153 .SS SUBPROCESS EVENTS
    154 The following events can be read on stdin:
    155 .TP
    156 .B DTMF [CHARACTER]
    157 When the client receives a DTMF character
    158 .TP
    159 .B CONNECTED
    160 When the remote end has picked up the phone
    161 .TP
    162 .B STOPPED [FILE]
    163 Playback of the given file has finished. This is also given when a file has been stopped
    164 with the
    165 .B STOP
    166 command
    167 .TP
    168 .B MESSAGE [STRING]
    169 The given message has been received.
    170 .
    171 .SS CALL TERMINATION
    172 When the remote end hangs up, or the call is terminated in any other manner,
    173 the process is killed via SIGTERM. the child may catch that signal for clean up.
    174 .
    175 .SH BUGS
    176 Call forwarding does not seem to work
    177 .
    178 .SH EXAMPLE
    179 An example, that plays the file
    180 .I message.wav
    181 and hangs up afterwords is shown in the following two sections.
    182 It calls every SIP URI it gets on the standard input and does the same process as above.
    183 .
    184 .SS PARENT PROCESS
    185 The parent process can be started as follows, and may then take SIP URIs via standard input.
    186 For every call it receives or places, 
    187 .I handler.sh
    188 is executed and passed the name of a file as first argument.
    189 Additionally, the remote ends are recorded in a log file
    190 .
    191 .HP
    192 .EX
    193 export SIPROC_USERNAME="max"
    194 export SIPROC_PASSWORD="max1234"
    195 export SIPROC_ID_URI='Max Muster <sip:max@sipproxy.com>'
    196 export SIPROC_REGISTRAR_URI='sip:sipproxy.com'
    197 
    198 while read uri
    199 do
    200 	echo "CALL $uri"
    201 done | siproc ./handle.sh message.wav
    202 .EE
    203 .
    204 .SS HANDLER
    205 This is the corresponding handler
    206 .I handle.sh
    207 that implements the call automation logic.
    208 If the call that is being handled is incoming, then the call ist answered first.
    209 Afterwords, the file given on $1 is played, and once that is done, the call hung up.
    210 .
    211 .HP
    212 .EX
    213 #!/bin/bash
    214 
    215 echo "$SIPROC_REMOTE_URI" >> log
    216 
    217 if [ "$SIPROC_OUTGOING" == "n" ]
    218 then
    219 	echo "ANSWER"
    220 fi
    221 
    222 while read line
    223 do
    224 	case "$line" in
    225 		"CONNECTED")
    226 			echo "PLAY $1"
    227 		;;
    228 		"STOPPED"*)
    229 			echo "HANGUP"
    230 		;;
    231 	esac
    232 done
    233 .EE
    234 .SH AUTHOR
    235 Dominik Schmidt (dominik@schm1dt.ch)