siproc

A primitive SIP client that spawns processes for each call
git clone git://xatko.vsos.ethz.ch/siproc.git
Log | Files | Refs | README

commit 88e0d385d012eddff7c09a53854190ec1a3d7f75
parent 8607879cd7cd34e9daea9d670529b7a5ca358cad
Author: Dominik Schmidt <dominik@schm1dt.ch>
Date:   Wed, 16 Oct 2019 10:07:03 +0200

Improve the man page

It now better adheres to the standard set in man-pages(7), and is generally
easier to understand (hopefully)

Diffstat:
Msiproc.1 | 99+++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------
1 file changed, 64 insertions(+), 35 deletions(-)

diff --git a/siproc.1 b/siproc.1 @@ -1,32 +1,57 @@ -.TH siproc 1 "2019-08-31" "0.0.1" "siproc man page" +.TH siproc 1 "2019-10-16" "0.0.1" "siproc man page" +. .SH NAME siproc \- a SIP softphone spawning processes for calls +. .SH SYNOPSIS .SY siproc .I /path/to/executable .RI [ args \&...] .YS +. .SH DESCRIPTION -siproc is a SIP client, that spawns the given process +siproc is a SIP client, that spawns the process given by .I /path/to/executable for every incoming or outgoing call, passing it the command line parameters .IR args . -Using standard input and output, these processes can interact with the peer and do tasks -like answering calls, playing files and many more. +.PP +Using standard input and output, these processes can exchange commands and events +with the parent process, that allow interaction with the caller/callee. +These command allow the program to answering calls, play files, send and receive +DTMF Tones et cetera. +On remote hangup, the child process is killed via SIGTERM. +. +.PP The account settings and other configuration are read via environment variables. -.SS MAIN PROGRAM COMMANDS -The main program reads some commands on stdin, terminated by newlines: +. +.SH EXIT STATUS +.IP 0 +on normal termination +.IP 1 +on program or configuration error (check standard error for details) +.SH ENVIRONMENT +Configuration parameters are given via environment variables .TP -.B QUIT -Terminates the program, disconnecting all calls. +.B SIPROC_REGISTRAR_URI +The server siproc should connect to, as a SIP URI (e.g "sip:myserver.tld") .TP -.B CALL [SIP URI] -Call a number, with -.B SIP URI -the address to be called, e.g. sip:contact@remote.tld +.B SIPROC_ID_URI +The ID URI of the account used, e.g. "Full Name <sip:Account@myserver.lan>" +.TP +.B SIPROC_USERNAME +The username of the account +.TP +.B SIPROC_USERNAME +The password of the account +.TP +.B SIPROC_TRANSPORT_PORT +The port used by siproc. This variable is optional, and defaults to 5060. +If you want to run multiple instances of siproc on the same machine, set +it to distinct values, since the softphone binds to it. +. .SS SUBPROCESS ENVIRONMENT VARIABLES -The processes invoked by siproc are passed various environment variables: +The processes spawned by siproc are passed the following environment variables: .TP .B SIPROC_REMOTE_URI The SIP URI of the remote end @@ -40,9 +65,26 @@ Some pjsip interna, look it up in their documentation of the struct CallInfo .B SIPROC_OUTGOING Whether the call being handled by this process is an incoming call (="n") or an outgoing call (="y") +. +.SH PROCESS COMMANDS AND EVENTS +This section will explain the communication protocol between the main process and +its children, as well as the commands the main process can be given on its standard +input. +. +.SS MAIN PROGRAM COMMANDS +The main program reads some commands on standard input, terminated by newlines ('\\n'): +.TP +.B QUIT +Terminates the program, disconnecting all calls. +.TP +.B CALL [SIP URI] +Call a number, with +.B SIP URI +the address to be called, e.g. sip:contact@remote.tld +. .SS SUBPROCESS COMMANDS -The process can then give commands via stdout and read events via stdin. -Each command or event is separated by a newline ('\n'). +The spawned child process can give commands via stdout and read events via stdin. +Each command or event is separated by a newline ('\\n'). The following commands are supported: .TP .B RINGING @@ -72,7 +114,9 @@ Stop the file that has been added last. Send a SIP message to the remote side .TP .B RECORD [FILE] -Record the conversation to the given file. If no file is given, the current recording is stopped. +Record the conversation to the given file. If no file is given, the current +recording is stopped. +. .SS SUBPROCESS EVENTS The following events can be read on stdin: .TP @@ -90,29 +134,14 @@ command .TP .B MESSAGE [STRING] The given message has been received. +. .SS CALL TERMINATION When the remote end hangs up, or the call is terminated in any other manner, -the process is killed via SIGTERM, so a program can catch that signal for cleaning up. -.SH ENVIRONMENT -Configuration parameters are given via environment variables -.TP -.B SIPROC_REGISTRAR_URI -The server siproc should connect to, as a SIP URI (e.g "sip:myserver.tld") -.TP -.B SIPROC_ID_URI -The ID URI of the account used, e.g. "Full Name <sip:Account@myserver.lan>" -.TP -.B SIPROC_USERNAME -The username of the account -.TP -.B SIPROC_USERNAME -The password of the account -.TP -.B SIPROC_TRANSPORT_PORT -The port used by siproc. This variable is optional, and defaults to 5060. -If you want to run multiple instances of siproc on the same machine, set it to different values. +the process is killed via SIGTERM. the child may catch that signal for clean up. +. .SH BUGS Call forwarding does not seem to work +. .SH AUTHOR Dominik Schmidt (dominik@schm1dt.ch)