NCID API Documentation

API 1.4
Last Edit: September 30, 2016
Copyright (C) 2010-2016
John L Chmielewski
Todd A Andrews

This document contains information needed to develop servers, clients, client output modules, and gateways for NCID (Network Caller ID).

All example phone numbers and names contained herein are intended to be fictional.

There are 5 feature sets of NCID conformance:

Table of Contents

Before you begin

ABOUT CONFIGURATION OPTIONS FOR SERVER IMPLEMENTATIONS

ABOUT FIELD PAIRS AND LINE TYPES

GENERAL NOTES ON NAME, NMBR, LINE AND MESG FIELD DATA

GENERAL NOTES ON DATE AND TIME FIELD DATA

ENSURING CONNECTIVITY WITH THE SERVER

COMPANION DOCUMENTS

Feature Set 1: Modem and Device Support

SERVER IMPLEMENTATION

Server Output Lines

Server Alias Support

Server Hangup Support

Modem-to-Server

Optional Server Extensions

Optional Server Hangup Extension

Optional NetCallerID Device-to-Server

Optional TCI Device-to-Server (new in API 1.1)

CLIENT IMPLEMENTATION

Client-to-Server

Optional Client-to-Module

Optional Client-to-TiVo Display

Feature Set 2: Gateway Support

SERVER IMPLEMENTATION

Server-to-Gateway

GATEWAY IMPLEMENTATION

Gateway-to-Server

Forwarding Gateway (Server-to-Server) (new in API 1.4)

CLIENT IMPLEMENTATION

Optional Client-to-Module

Feature Set 3: Client Job Support

OVERVIEW OF AVAILABLE CLIENT JOBS

SERVER IMPLEMENTATION

Server Output Lines

CLIENT IMPLEMENTATION

Client-to-Server

CLIENT JOB EXAMPLES

Feature Set 4: Acknowledgment Support

SERVER IMPLEMENTATION

Server Output Lines

GATEWAY IMPLEMENTATION

Gateway-to-Server

CLIENT IMPLEMENTATION

Client-to-Server

Feature Set 5: Relay Job Support (new in API 1.4)

RELAY JOB OVERVIEW

SERVER IMPLEMENTATION

RELAY JOB ORIGIN (RJO) IMPLEMENTATION

RJO Line Type Definition

RELAY JOB TARGET (RJT) IMPLEMENTATION

RJT Line Type Definition

RELAY JOB EXAMPLES

Sending a Text Message

Country Codes

Emulation Programs and Test Files

Appendix A: Quick Reference List of all call type line identifiers

Appendix B: Index to all line type definitions

Appendix C: Quick Reference List of all server configuration settings

Appendix D: More info about modem MESG hexadecimal characters

Appendix E: SMS Relay Job sequence diagram (new in API 1.4)

API Version Change History

Release Summary

Version 1.4

Version 1.3

Version 1.2

Version 1.1

Version 1.0

Documentation Change History

September 30, 2016

July 23, 2016

May 7, 2016

December 29, 2015

Before you begin

ABOUT CONFIGURATION OPTIONS FOR SERVER IMPLEMENTATIONS

This API document attempts to describe server interactions with gateways, client, extensions, etc. without regard to a specific operating system or specific programming methods and conventions. However, for the purpose of reading this document we will reference configuration options using the following convention:

<configuration file name::setting name>

In the case of the official NCID distribution for Unix/Linux platforms, there are several configuration files. Here are just a few of them:

Purpose Unix/Linux File Name Convention used in this API
Server settings ncidd.conf <ncidd.conf::setting name>
Alias mappings ncidd.alias <ncidd.alias::alias definition>
Blacklist ncidd.blacklist <ncidd.blacklist::call name or number>
Whitelist ncidd.whitelist <ncidd.whitelist::call name or number>
Universal Client settings ncid.conf <ncid.conf::setting name>
SIP Gateway settings sip2ncid.conf <sip2ncid.conf::setting name>
YAC Gateway settings yac2ncid.conf <yac2ncid.conf::setting name>

An example of a setting name in the server configuration file would be lockfile. Within this document you would see the setting referenced as ncidd.conf::lockfile.

If a developer wishes to create his or her own NCID server, any configuration file name and setting name convention desired can be used. For example, an NCID server for Windows might use a file name called ncid-server.ini and a setting called LockFile=.

Using the <configuration file name::setting name> convention allows a developer to correlate the setting names referenced in this API with the developer's own conventions. In this regard, you can think of <configuration file name::setting name> as a reference to a concept or definition. ncidd.conf::lockfile therefore refers to the path of the server's serial port lock file. An alphabetized summary of all server options, including a brief description, can be found in Appendix C: Quick Reference List of all server configuration settings.

ABOUT FIELD PAIRS AND LINE TYPES

The reason for the following restrictions is to allow future NCID programs and scripts to be as backward compatible as possible. This is particularly important in the case of third party software that may not be updated at the same time as a new NCID release.

Field Pairs

A field pair is defined as <field label><field data>, with zero or more delimiter characters between them.

The very first field pair for a line might begin with the three characters ### to indicate the data is being sent TO the server, or begin with the three characters *** to indicate the data is being received FROM the server.

It is very important NOT to assume that the order of field pairs will always be the same across NCID versions.

For example, if today a hypothetical layout of field pairs looks like this:

XYZ: ***DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*

There is no guarantee that the order won't be changed. Perhaps a future version would swap MESG and NAME:

XYZ: ***DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*NAME*<name>*MESG*<hexchars>*

Another example showing ###/.../+++ field delimiters for the field pairs:

ABCD: ###DATE<datetime>...CALL<type>...LINE<lineid>...NMBR<number>...NAME<name>+++

might someday get changed to put NMBR and NAME first:

ABCD: ###NMBR<number>...NAME<name>...DATE<datetime>...CALL<type>...LINE<lineid>+++

Any programs or scripts you develop on your own must be flexible in parsing out <field label><field data>, wherever they might be located in a line.

** It is very important for a program or script to ignore <field label><field data> pairs that it does not recognize. **

For example, if at some point in the future a new field pair with the hypothetical label of JJJJ was added, your programs or scripts should not trigger a fatal error. And it might be added at any location in the line, not just at the end:

XYZ: ***DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*JJJJ*<data>*MESG*<hexchars>*NAME*<name>*

ABCD: ###DATE<datetime>...CALL<type>...LINE<lineid>...NMBR<number>...JJJJ<data>...NAME<name>+++

Line Types

GENERAL NOTES ON NAME, NMBR, LINE AND MESG FIELD DATA

NAME

NMBR

LINE

MESG

The Dash

GENERAL NOTES ON DATE AND TIME FIELD DATA

DATE

The general rule of thumb is that dates related to call data will already be passed from the telco to NCID in the correct format for the country where NCID is running -- month/day or day/month -- as provided by the modem or other device. They will in turn be stored in the call log in the same format.

There are two exceptions:

(New in API 1.4) The field pair contents of RLY: line types are NOT checked at all and are expected to include the DATE field pair.

  • DATE, which will come from the modem or device and falls under the general rule of thumb above
  • SCALL and ECALL, which represent the start and end of a call for call accounting, will always be in the format month/day.

<datetime>

TIME

(New in API 1.4) The field pair contents of RLY: line types are NOT checked at all and are expected to include the TIME field pair.

ENSURING CONNECTIVITY WITH THE SERVER

There are three different methods that clients and gateways can use to test their connection to the server.

Supported in Feature Set 1. This is the most basic method. A client or gateway simply sends a to the server and checks for errors. The server will make a note in its log that it received a blank line, but otherwise ignores it. The server does not send any response.

Supported in Feature Set 2. A client or gateway can send REQ: YO and expect an ACK: REQ YO response from the server.

Supported in Feature Set 4. A client or gateway can send REQ: ACK <commands and arguments> and expect an ACK: REQ ACK <commands and arguments> response from the server. ACK: REQ ACK sets an "ack" flag for the client that tells the server to acknowledge gateway CALL:, CALLINFO:, and NOT: lines. In other words, the server is expected to echo back all commands and arguments it receives.

COMPANION DOCUMENTS

You may wish to have the following documents handy as you work with the API:

User Manual:

Feature Set 1: Modem and Device Support

SERVER IMPLEMENTATION

If you want to implement a server to communicate with NCID clients and gateways:

  • send a 200 text message to identify the server and version
  • send a 210 text message to identify the API version and supported feature sets
  • check server ncidd.conf::send cidlog to determine whether to send the call log
  • if not configured to send it, send a 251 Call log not sent message
  • if configured to send it but it is empty, send a 252 Call log empty message
  • if configured to send it but the file does not exist, send a 253 No call log message
  • if configured to send it and it is not empty, send the call log and end with a 250 End of call log message
  • optionally, send a list of server-supported Client Job options to client, one OPT: <option> line for each option
  • send a 300 End of server startup message
  • putting all of the above together, a typical client connection start-up looks like this: >
    200 Server: ncidd (NCID) x.x
    210 API x.x Feature Set x x x x ...
    CIDLOG: DATE12012015TIME0028LINEHOMENMBR...
    HUPLOG: DATE12012015TIME0105LINEHOMENMBR...
    ...
    250 End of call log
    OPT: hangup-1
    OPT: ...
    300 End of connection startup
  • if configured by ncidd.conf::send cidinfo to send ring info, send a CIDINFO: line at each ring with a LINE indicator (default '-') and the ring count
  • generate an alias for the name, number and/or line if it is in the alias file
  • if optional Internal Hangup support (ncidd.conf::hangup) is implemented:
  • hangup a call if it is in the ncidd.alias file but not in the ncidd.whitelist file
  • send a HUP: line to connected clients when an incoming call is automatically terminated
  • otherwise, if the call is not being terminated, send a CID: line to connected clients when a call is received
  • send a CIDINFO: line after ringing stops, with a ring count of 0

Server Output Lines

When the server sends information to a client or gateway, it sends the data as lines of text that start with a line label. This defines line types. The current line labels are:

The server version message. The wording stays the same, but the version number changes each time the server is updated.

For example, if the server was version 1.0:

200 Server: ncidd (NCID) 1.0

The server API version and feature sets. This is to inform clients and gateways what features are implemented. All supported feature sets must be included.

For example, if the API version is 1.0 then four feature sets are supported:

210 API 1.0 Feature Set 1 2 3 4

A call log message sent at server startup:

250 End of call log

251 Call log not sent

252 Call log empty

253 No Call log

End of the connection startup message:

300 End of connection startup

An incoming Caller ID text line. It is sent to the clients and saved in the call log when a call is received. The text line is comprised of field pairs, the first contains the field label and the second contains the field data. Fields are separated by a * and the first field starts after a *:

CID: *DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*

(New in API 1.4) A +CID: line is the same as CID: except the leading "+" indicates it is coming from a Forwarding Gateway.

The CID: line has the following field pairs:

<label>*<data>* Description
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
LINE*lineid* where lineid is a string of characters, NO-LINE or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
MESG*hexchars* where hexchars is a string of characters or NONE
NAME*name* where name is a string of characters, NO NAME or -

When the server sends the call log, it replaces the CID: label with CIDLOG:.

If optional Internal Hangup support (ncidd.conf::hangup) is implemented, then when a call is automatically terminated, a HUP: (Hung Up Phone) line is created by replacing the CID: label with the HUP: label. The text line has the same fields and format as the CID: text line:

HUP: *DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*

(New in API 1.4) A +HUP: line is the same as HUP: except the leading "+" indicates it is coming from a Forwarding Gateway.

The HUP: line has the following field pairs:

<label>*<data>* Description
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
LINE*lineid* where lineid is a string of characters, NO-LINE or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
MESG*hexchars* where hexchars is a string of characters or NONE
NAME*name* where name is a string of characters, NO NAME or -

When the server sends the call log, it replaces the HUP: label with HUPLOG:.

A text line containing a message, either a server warning message or a user generated message that is sent to the clients and saved in the call log:

MSG: <message>***DATE*<date>*TIME*<time>*NAME*<name>*NMBR*<number>*LINE*<lineid>*MTYPE*<io>*

(New in API 1.4) A +MSG: line is the same as MSG: except the leading "+" indicates it is coming from a Forwarding Gateway.

The MSG: line has the following field pairs:

<label>*<data>* Description
*** start of the information part of the message being sent from the server
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
NAME*name* where name is a string of characters, NO NAME or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
LINE*lineid* where lineid is a string of characters, NO-LINE or -
MTYPE*io* where io is either IN, OUT or -

Examples:

MSG: Caller ID Logfile too big: (95000 > 90000) bytes ***DATE ...  
MSG: This is a user message ***DATE ...

When the server sends the call log, it replaces the MSG: label with MSGLOG:.

A text line that indicates the telephone LINE identifier and ring information. The text line is comprised of field pairs, the first contains the field label and the second contains the field data. Fields are separated by a * and the first field starts after a *. The ring information is only obtained from modems that indicate each ring and gateways that use ring to indicate the type of hangup. Note that "hangup" for CIDINFO: lines does not refer to automatic Internal Hangups or Hangup Extensions. Instead, it refers to a person on the phone who triggers the hangup manually, or the telco that ends a call that has not been answered after a certain number of rings.

CIDINFO:*LINE*<lineid>*RING*<count>*TIME*<time>*

(New in API 1.4) A +CIDINFO: line is the same as CIDINFO: except the leading "+" indicates it is coming from a Forwarding Gateway.

The CIDINFO: line has the following fields:

<label>*<data>* Description
LINE*lineid* where lineid is a string of characters, NO-LINE or -
RING*count* where number is 0, -1, -2 or the ring count
 0 = ringing has stopped because call was answered
-1 = ringing has stopped, call was not answered
-2 = call hangup after being answered
TIME*time* where time is hh:mm:ss in 24-hour format, h = hour, m = minute, s=second

Ring indication example sent to the clients for ring count 4 and line 1: > CIDINFO: *LINE*1*RING*4*TIME*16:20:05*

Example of a POTS line label and the end of ringing indicator: > CIDINFO: *LINE*POTS*RING*0*TIME*16:20:05*

A SIP gateway example indicating hangup before answer and a VOIP line label: > CIDINFO: *LINE*VOIP*RING*-1*TIME*16:20:05*

A SIP gateway example indicating hangup after answer and a VOIP line label: > CIDINFO: *LINE*VOIP*RING*-2*TIME*16:20:05*

A server option sent to all the clients. It has only one field so there can only be one option per line, however, multiple OPT: lines are permitted. Unless otherwise indicated, options are always in lowercase.

At present, there are four options:

OPT: hangup-X
OPT: hupmode-X
OPT: ignore1
OPT: regex

They are sent only if the corresponding ncidd.conf::hangup, ncidd.conf::hupmode, ncidd.conf::ignore1 and ncidd.conf::regex settings are enabled. The "X" in OPT: hangup-X and OPT: hupmode-X represents the hangup mode in the range 1-3.

(New in API 1.3) All OPT: lines output by the server are for informational and troubleshooting purposes only. Clients can optionally make use of them by giving the user a way to display them. Otherwise, clients are not required to display them, do not need to take any action on them and can safely ignore them. See Feature Set 1: Client Implementation for more information.

When the server sends the call log, it adds the LOG: tag to every line that does not contain a recognized line label. The following is an example of a comment line that may be in the file:

LOG: # comment line

Server Alias Support

The name, number, and telephone line of a call are checked for an alias. If a match is found it will be replaced by its alias before the call is added to the call log and before the call information is sent to the clients.

NCID's support for aliases is extensive and there is an entire section in the User Manual devoted to the subject (see the chapter "Using NCID"). Continue reading below for:

Alias support is required in Feature Set 1.

Clients implementing Feature Set 3: Client Job Support, can also be used to maintain aliases. Such clients will also provide a way to force the server to reload its alias table.

Alias Types

There are six types of aliases. The text in the Code column below is used internally by NCID to distinguish the types and you'll see it used throughout this document.

Type Code
number NMBRONLY
name NAMEONLY
number & name NMBRNAME
number if name NMBRDEP
name if number NAMEDEP
lineid LINEONLY
Alphabetical list of related configuration options:
  • ncidd.conf::cidalias
  • ncidd.conf::ignore1
  • ncidd.conf::lineid
  • ncidd.conf::regex

Server Hangup Support

At a high-level, there are two sets of procedures available to automatically hangup calls. Both are optional, and one or both can be enabled at the same time. They are:

Internal Hangups are described below. Hangup Extensions are optional.

When Caller ID is received from a modem, and if the caller name or number is in the blacklist file but not the whitelist file, hangup is automatic.

NCID's support for automatic hangups is extensive and there is an entire section in the User Manual devoted to the subject (see the chapter "Using NCID"). Continue reading below for:

Internal Hangup support is optional in Feature Set 1.

Clients implementing Feature Set 3: Client Job Support, can also be used to maintain the blacklist and whitelist. Such clients will also provide a way to force the server to reload these tables.

When the server hangs up the line, it sends a HUP: line to the clients and call log. The HUP: line has the same layout as the CID: line generated from the call, but with CID: replaced by HUP:.

Internal Hangup Types

If enabled by ncidd.conf::hangup, there are three types of hangups:

  • Normal (required)

When the server receives the Caller ID and if the name or number is in the blacklist file but not the whitelist file, the modem does a pickup, delays for one second, and then does a hangup.

Action Send this AT command
PICKUP the line ATH1
delay 1 second  
HANGUP ATH0
  • FAX (optional)

When the server receives the Caller ID and if the name or number is in the blacklist file but not the whitelist file, the modem sets FAX mode, does a FAX answer, generates a FAX tone, delays for 10 seconds, hangs up, and resets to data mode.

Action Send this AT command Expected modem response
Set FAX Mode AT+FCLASS=1 OK
* PICKUP the line ATH1 OK
FAX Answer ATA
delay 10 seconds
HANGUP ATH0 OK
Set DATA Mode AT+FCLASS=0

* NOTE: PICKUP is a configuration option. Older modems will fail to generate a FAX tone if there is a PICKUP.

  • Announce (optional)

When the server receives the Caller ID and if the name or number is in the blacklist file but not the whitelist file, the modem sets VOICE mode, answers the call, plays a recording, hangs up, and resets to data mode.

Action Send this AT command Expected modem response
Set VOICE Mode AT+FCLASS=8 OK
Set speaker volume to normal AT+VGT=128 OK
* Select compression method AT+VSM=130 OK
Answer call AT+VLS=1 OK
Set echo off ATE0 OK
Select VOICE TRANSFER Mode AT+VTX CONNECT
Send recording to modem
Send end of recording <DLE><ETX> OK
Set echo on ATE1 OK
HANGUP ATH0 OK
Set DATA Mode AT+FCLASS=0

* NOTE: AT+VSM=130 is the default compression method used for the Conexant CX93001 chipset used in a lot of modems.

Alphabetical list of related server configuration options:
  • ncidd.conf::announce
  • ncidd.conf::audiofmt
  • ncidd.conf::blacklist
  • ncidd.conf::hangup
  • ncidd.conf::ignore1
  • ncidd.conf::initcid
  • ncidd.conf::initstr
  • ncidd.conf::lockfile
  • ncidd.conf::nomodem
  • ncidd.conf::noserial
  • ncidd.conf::pickup
  • ncidd.conf::regex
  • ncidd.conf::ttyclocal
  • ncidd.conf::ttyport
  • ncidd.conf::ttyspeed
  • ncidd.conf::whitelist

Modem-to-Server

The modem should be configured to output as shown in the example below. The order of the lines is unimportant and some of the lines may not be present. For example, the MESG line is normally not emitted by modems.

There may or may not be a space before the '='.

The NMBR label may be DDN_NMBR (Dialable Directory Number) instead, depending on the country.

The modem output is expected before the second ring and in most instances will be after the first ring, but not always:

RING    

MESG = 110101    
DATE = 0511    
TIME = 1852    
NMBR = 4075550000 or DDN_NMBR = 4075550000    
NAME = JOHN DOE

RING

Optional Server Extensions

A Server Extension is an optional external script or program that is called by ncidd to perform a function and return a result. Server Extensions are a way for users to add functionality to NCID without requiring changes to NCID itself, especially when the functionality is atypical and would not have a broad appeal to other NCID users.

Server Extensions are isolated from the main NCID distribution, and because of this they do not normally require any changes when NCID is upgraded to a later version.

One of the design philosophies that has always existed with NCID is to accept incoming caller ID as quickly as possible, and to send it to all connected clients as quickly as possible. With a Server Extension, there is a risk that executing one can impact performance. For this reason, users are cautioned to create Server Extensions that are optimized for fast execution.

The overall theory of operation is that ncidd will pass call info to the Server Extension, it will do whatever processing is desired, and return back to ncidd some sort of result.

In order for ncidd to use Server Extensions, there is a minimal amount of configuration information required in ncidd.conf. Typically this consists of a setting to enable/disable the Server Extension, and a setting to tell ncidd the Server Extension name. Server Extensions may have specific options that also need to be in ncidd.conf.

Beyond the minimal info needed to make ncidd aware of the Server Extension, there is no reason that a Server Extension could not have its own configuration file.

You can use any scripting or programming language desired, however, if it is a scripting language and not a compiled binary, the first line must use the normal Unix convention of a "#!" path to the interpreter.

Examples:
#!/bin/bash
#!/usr/bin/perl

Currently the only Server Extension supported is the Optional Server Hangup Extension.

Optional Server Hangup Extension

You might want to implement a Hangup Extension if you want additional or alternative call termination checking beyond the basic Internal Hangup that's implemented with the ncidd.blacklist and ncidd.whitelist files. All ncidd.conf::hangup modes (normal, fax, announce) are supported.

One advantage that Hangup Extensions have over the basic Internal Hangup is the ability to associate a different ncidd.conf::announce file for every caller ID number or name.

The Hangup Extensions script determines what calls to hang up on. It does not use ncidd.blacklist but does use ncidd.whitelist. If the call is in ncidd.whitelist or if the basic Internal Hangup is enabled and has hung up on the call, the hangup script is not executed.

Alphabetical list of related server configuration options:

  • ncidd.conf::hupmode
  • ncidd.conf::hupname
  • ncidd.conf::huprmd

The ncidd.conf::hupname file must begin with hangup-.

ncidd passes one string of call info as a single command line argument. It passes it at the point just prior to changing the line type from CID: to HUP:. ncidd must wait for the Hangup Extension response data before continuing.

The string of call info has the following format and is subject to the rules described in About field pairs and line types.

*DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*NAME*<name>*

It has the following fields:

<label>*<data>* Description
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
LINE*lineid* where lineid is a string of characters, NO-LINE or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
NAME*name* where name is a string of characters, NO NAME or -

Data to be passed back from the Hangup Extension to ncidd must be sent to STDOUT.

Format 1: > hangup|OK

Format 2, when ncidd.conf::hupmode = 3 you can specify an optional voice file: > Recording:<file name or full path>
> hangup|OK

The Recording: line must be sent prior to the hangup line. If it is not present, it will default to the voice file in ncidd.conf::huprmd. If ncidd.conf::huprmd is not defined, the ncidd.conf::announce voice file will be used.

If and only if hangup is passed back to ncidd will the call be immediately terminated. Passing back OK is not required (no response at all is also acceptable) but it is suggested because you'll be able to see it in ncidd.log.

Optional NetCallerID Device-to-Server

The NetCallerID serial device outputs the Caller ID on a single line with the following format:

###DATE<datetime>...NMBR<number>...NAME<words>+++\r

The NetCallerID line has the following fields:

<label><data> Description
### start of the information part of the message being sent to the server
DATEdatetime where datetime is mmddhhmm or ddmmhhmm, m = month, d = day, h = hour, m = minute
... field separator
NMBRnumber where number is the phone number
... field separator
NAMEwords where words is a name or -UNKNOWN CALLER- or -MSG OFF- or similar
+++ end of the information part of the message

Examples:

###DATE03301423...NMBR4075551212...NAMEWIRELESS CALL+++\r    
###DATE03301423...NMBR...NAME-UNKNOWN CALLER-+++\r    
###DATE03301423...NMBR...NAME+++\r    
###DATE...NMBR...NAME-MSG OFF-+++\r    

Optional TCI Device-to-Server (new in API 1.1)

Serial TCI devices output a single line using the Telephone Collectors International output standard.

To make sure the text line is from a TCI device, the server tests to make sure all of the following are true:

line length > 30 characters
position 0 is a digit
position 9 is a '/'
position 24 is an 'M'

The TCI line has the following fields:

Positions Length Description
0-1 2 LINE
7-11 5 DATE
17-24 8 TIME
29-43 15 NUMBER
55-69 15 NAME

Example:

01      9/03      2:25 PM       806-672-1767           WIRELESS CALLER
0123456789012345678901234567890123456789012345678901234567890123456789
          1         2         3         4         5         6

NOTE:

All fields except NAME are right justified. Five spaces separate each field, except NUMBER and NAME fields which are separated by 11 spaces.

CLIENT IMPLEMENTATION

  • will end with a 250 End of call log message
New in API 1.3

All OPT: lines output by the server are for informational and troubleshooting purposes only. Clients can optionally make use of them by giving the user a way to display them. Otherwise, clients are not required to display them, do not need to take any action on them and can safely ignore them. See also Feature Set 1 OPT: definition for more information.

If a client wants to optionally display the OPT: lines then it will need to do the following: - Retrieve all OPT: lines during the initial connection to the server.
- Have a way for users to easily view the OPT: lines. They can be displayed however is convenient for the programming language the client is written in. Displaying the leading OPT: text is optional, but the text following OPT: must be shown.
- Handle OPT: hangup (i.e., with no dash-value) in order to accommodate servers that are not yet compliant with API 1.3.
- Show "none" if no OPT: lines were received.

It is suggested, but not required:
- That the lines be shown in a vertical list. - That user-friendly text be shown to allow easy interpretation of the setting.
- That the lines be shown in a Help Menu.

Examples below show OPT: hangup for a pre-API 1.3 server, and OPT: hangup-3, even though they won't both be generated by the same server.

Minimum suggested examples:

 Server-enabled options:  
 OPT: hangup  
 OPT: hangup-3  
 OPT: hupmode-2  
 OPT: ignore1  
 OPT: regex 

or

 Server-enabled options:  
 hangup  
 hangup-3  
 hupmode-2  
 ignore1  
 regex 

or

 Server-enabled options:  
 none

Ideal suggested examples showing all options:

Server-enabled option Description
none  
hangup Server Hangup: Terminate Blacklisted Call
hangup-1 Internal Hangup Mode 1: Terminate Blacklisted Call
hangup-2 Internal Hangup Mode 2: Generate FAX Tone and Terminate Blacklisted Call
hangup-3 Internal Hangup Mode 3: Play Announcement and Terminate Blacklisted Call
hupmode-1 Hangup Extension Mode 1: Terminate Blacklisted Call
hupmode-2 Hangup Extension Mode 2: Generate FAX Tone and Terminate Blacklisted Call
hupmode-3 Hangup Extension Mode 3: Play Announcement and Terminate Blacklisted Call
ignore1 Server Ignores Leading 1 for Calls/Aliases
regex Use Regular Expressions for Server List Matching
(anything else) Unknown/invalid

Client-to-Server

Clients are allowed to send a '\n' to the server to determine if the server is still available. It should be sent only after at least 15 minutes of no server activity. There is no server response, however, the server will log this action as "Client xxx sent empty line." It is up to the client to check to see if sending a '\n' results in an error and take appropriate action (e.g., try to reconnect to the server).

If a client needs a more robust way of making sure the server is still available by requiring a server response, implement Feature Set 4: Acknowledgment Support.

A user generated text line sent to the server and converted into a server MSG: text line when the message is received.

MSG: <message>###DATE*<date>*TIME*<time>*NAME*<name>*NMBR*<number>*LINE*<lineid>*MTYPE*<io>*

(New in API 1.4) A +MSG: line is the same as MSG: except the leading "+" indicates it is coming from a Forwarding Gateway.

The MSG: line has the following field pairs (field label and field data):

<label>*<data>* Description
### start of the information part of the message being sent to the server
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
NAME*name* where name is a string of characters, NO NAME or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
LINE*lineid* where lineid is a string of characters, NO-LINE or -
MTYPE*io* where io is either IN, OUT or -

Optional Client-to-Module

When the client is configured to use an output module, it splits the single server call line into eight lines for passing via standard input to the output module.

<date>\n<time>\n<number>\n<name>\n<lineid>\n<input type>\n<""|message>\n<message type>\n

The contents of each line are as follows:

Line Field Description
1 date mm/dd/yyyy or dd/mm/yyyy date of either the call or message
where m = month, d = day, y = year
2 time hh:mm or hh:mm am/pm Time of either the call or message
where h = hour, m = minute
3 number Number of either the call or message
4 name Who made the call
5 lineid Lineid of either the call or message
6 input type CID OUT WID HUP BLK MSG PID NOT
7 message Message, or blank for a call
8 message type If <input type> indicates a call then <message type> will be null. Otherwise, <message type> will be IN, OUT or -.

Optional Client-to-TiVo Display

If the TiVo (--tivo|-T) option is given on the command line when launching the ncid client, or the TivoFlag is set to 1 in ncid.conf, the output is two lines. The first line contains the Caller ID name and number. The second line contains the type of call and a telephone lineid. If the lineid is blank, then there is no second line:

PASADENA, CA (800)555-1212

PASADENA, CA (800)555-1212  
CID POTS

Feature Set 2: Gateway Support

SERVER IMPLEMENTATION

If you want to implement a server to communicate with NCID clients and gateways:

  • an END: line, and
  • a CIDINFO: line with CANCEL if the ring count is -1, or
  • a CIDINFO: line with BYE if the ring count is -2

Server-to-Gateway

An outgoing call text line.

The text line has the same fields and format as the CID: text line:

OUT: *DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*

(New in API 1.4) An +OUT: line is the same as OUT: except the leading "+" indicates it is coming from a Forwarding Gateway.

The OUT: line has the following field pairs (field label and field data):

<label>*<data>* Description
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
LINE*lineid* where lineid is a string of characters, NO-LINE or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
MESG*hexchars* where hexchars is always NONE
NAME*name* where name is a string of characters, NO NAME or -

When the server sends the call log, it replaces the OUT: label with OUTLOG:.

A smartphone incoming Caller ID text line sent to NCID. It uses the PID: label instead of the CID: label because two client output modules (ncid-page and ncid-notify) can be configured to send CID: and MSG: text lines to smartphones. This could cause the same message so be sent back and forth in an infinite loop if CID: or MSG: were used. The text line has the same fields and format as the CID: text line:

PID: *DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*

(New in API 1.4) A +PID: line is the same as PID: except the leading "+" indicates it is coming from a Forwarding Gateway.

The PID: line has the following field pairs (field label and field data):

<label>*<data>* Description
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
LINE*lineid* where lineid is a string of characters, NO-LINE or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
MESG*hexchars* where hexchars is always NONE
NAME*name* where name is a string of characters, a name from the smartphone address book (use "UNKNOWN" if not in the address book), NO NAME or -

When the server sends the call log, it replaces the PID: label with PIDLOG:.

A Call Waiting Caller ID text line. (New in API 1.1)

The text line has the same fields and format as the CID: text line:

WID: *DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*

(New in API 1.4) A +WID: line is the same as WID: except the leading "+" indicates it is coming from a Forwarding Gateway.

The WID: line has the following field pairs (field label and field data):

<label>*<data>* Description
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
LINE*lineid* where lineid is a string of characters, NO-LINE or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
MESG*hexchars* where hexchars is a string of characters or NONE
NAME*name* where name is a string of characters, NO NAME or -

When the server sends the call log, it replaces the WID: label with WIDLOG:.

An end of call text line. It is generated from the CALLINFO: text line from a gateway. It provides information that can be used for call accounting.

END: *HTYPE*<ec>*DATE*<date>*TIME*<time>*SCALL*<dt>*ECALL*<dt>*CTYPE*<io>*LINE*<lineid>*NMBR*<number>*NAME*<name>*

(New in API 1.4) An +END: line is the same as END: except the leading "+" indicates it is coming from a Forwarding Gateway.

The END: line has the following field pairs (field label and field data):

<label>*<data>* Description
HTYPE*ec* where ec = BYE or CANCEL
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
SCALL*date time* where start of call date is mm/dd/yyyy, a space, and time is hh:mm:ss in 24-hour format, m = month, d = day, y = year, h = hour, m = minute, s=second
ECALL*date time* where end of call date is mm/dd/yyyy, a space, and time is hh:mm:ss in 24-hour format, m = month, d = day, y = year, h = hour, m = minute, s=second
CTYPE*io* where io is either IN or OUT
LINE*lineid* where lineid is a string of characters, NO-LINE or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
NAME*name* where name is a string of characters, NO NAME or -

When the server sends the call log, it replaces the END: label with ENDLOG:.

When a call is automatically blocked, a BLK: (Call Blocked) line is created. A blocked call is one where the CID device (e.g., Whozz Calling Ethernet Link devices) does not pass an incoming call through to connected telephones. The calling party simply hears the line ringing. Compare this with a terminated (HUP:) call where the calling party hears the line disconnect, and may or may not hear the line ringing at all.

The text line has the same fields and format as the CID: text line:

BLK: *DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*

(New in API 1.4) A +BLK: line is the same as BLK: except the leading "+" indicates it is coming from a Forwarding Gateway.

The BLK: line has the following field pairs (field label and field data):

<label>*<data>* Description
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
LINE*lineid* where lineid is a string of characters, NO-LINE or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
MESG*hexchars* where hexchars is always NONE
NAME*name* where name is a string of characters, NO NAME or -

When the server sends the call log, it replaces the BLK: label with BLKLOG:.

A notification text line of a smartphone message. It is sent to all clients and saved in the call log. The text line has the same fields and format as the MSG: text line.

NOT: <message>***DATE*<date>*TIME*<time>*NAME*<name>*NMBR*<number>*LINE*<lineid>*MTYPE*<io>*

(New in API 1.4) A +NOT: line is the same as NOT: except the leading "+" indicates it is coming from a Forwarding Gateway.

The NOT: line has the following field pairs (field label and field data):

<label>*<data>* Description
*** start of the information part of the message being sent from the server
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
NAME*name* where name is a string of characters, NO NAME or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
LINE*lineid* where lineid is a string of characters, NO-LINE or -
MTYPE*io* where io is either IN, OUT or -

Examples:

NOT: PHONE 4012: PING Test notification ***DATE ...  
NOT: PHONE 7cd0: SMS from mail@nowhere.com ***DATE ...

When the server sends the call log, it replaces the NOT: label with NOTLOG:.

GATEWAY IMPLEMENTATION

Gateway-to-Server

When the gateway sends information to the server, it sends the data as lines of text that start with a line label. This defines line types. The current line labels are:

A gateway Caller ID text line. It is sent to the server and converted into a CID:, PID:, OUT:, WID:, HUP: or BLK: text line when a call is received. The text line is comprised of field pairs, one contains the field name and the following field contains the field data. Fields are separated by ..., the first field starts after ###, and the last field ends in +++:

CALL: ###DATE<datetime>...CALL<type>...LINE<lineid>...NMBR<number>...NAME<name>+++

The CALL: line has the following field pairs (field label and field data):

<label><data> Description
### start of the information part of the message being sent to the server
DATEdatetime where datetime is mmddhhmm or ddmmhhmm, m = month, d = day, h = hour, m = minute
... field separator
CALLtype where type is IN, OUT, PID, HUP, BLK, or WID
... field separator
LINElineid where lineid is a string of characters, NO-LINE or -
... field separator
NMBRnumber where number is a string of characters, NO-NUMBER or -
... field separator
NAMEname where name is a string of characters, NO NAME or -
+++ end of the information part of the message

If the gateway is on a smart phone or connects to a smart phone, the CALLtype must be PID instead of IN.

A text line that indicates the telephone lineid and call start/end information. It is sent to the server and converted into an END: text line when a call completes. The text line is comprised of field pairs, the first contains the field name and the second contains the field data. Fields are separated by ..., the first field starts after ###, and the last field ends in +++. The call start/end information is only obtained from gateways that provide such info:

CALLINFO: ###<end>...DATE<datetime>...SCALL<dt>...ECALL<dt>...CALL<type>...LINE<lineid>...NMBR<tn>...NAME<name>+++

The CALLINFO: line has the following fields:

<label><data> Description
### start of the information part of the message being sent to the server
end where end is either BYE or CANCEL
... field separator
DATEdatetime where datetime is mmddhhmm or ddmmhhmm, m = month, d = day, h = hour, m = minute
... field separator
SCALLdate time where start of call date is mm/dd/yyyy, a space, and time is hh:mm:ss in 24-hour format, m = month, d = day, y = year, h = hour, m = minute, s=second
... field separator
ECALLdate time where end of call date is mm/dd/yyyy, a space, and time is hh:mm:ss in 24-hour format, m = month, d = day, y = year, h = hour, m = minute, s=second
... field separator
CALLtype where type is IN or OUT or PID or HUP or BLK
... field separator
LINElineid where lineid is a string of characters, NO-LINE or -
... field separator
NMBRnumber where number is a string of characters, NO-NUMBER or -
... field separator
NAMEname where name is a string of characters, NO NAME or -
+++ end of the information part of the message

A notification text line of a smartphone message. It is sent to the server and converted into an NOT: text line when a smartphone notification is received. The text line is comprised of field pairs, one contains the field name and the following field contains the field data. Fields are separated by *, the first field starts after ###, and the last field ends in *:

NOT: <message> ###DATE*<date>*TIME*<time>*NAME*<name>*NMBR*<number>*LINE*<lineid>*TYPE*<io>*

(New in API 1.4) A +NOT: line is the same as NOT: except the leading "+" indicates it is coming from a Forwarding Gateway.

The NOT: line has the following field pairs (field label and field data):

<label>*<data>* Description
### start of the information part of the message being sent to the server
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
NAME*name* where name is a string of characters, NO NAME or -
NMBR*number* where number is a string of characters, NO-NUMBER or -
LINE*lineid* where lineid is a string of characters, NO-LINE or -
MTYPE*io* where io is either IN, OUT or -

Forwarding Gateway (Server-to-Server) (new in API 1.4)

You might want to implement a Forwarding Gateway in the following scenarios:

Distributed with NCID is the ncid2ncid gateway which allows up to four sending servers to be combined and transmitted to a single receiving server.

There needs to be a method to distinguish which call activity is being forwarded. This method involves prefixing line types with a "+". When ncid2ncid collects call activity from the sending servers, it adds the "+" before transmitting it to the single receiving server. The receiving server (an instance of ncidd) strips the "+" and sends the call activity to all listening clients.

Here's a hypothetical example: Two Raspberry Pi computers are running ncidd and each have their own modem to monitor. A third computer running Fedora has no access to modems but does have an Apple iPad and an Android tablet connecting as ncid clients. All of these devices are on the same network subnet.

This will require ncid2ncid to be configured such that RPi#1 and RPi#2 are two sending servers and the Fedora computer is the receiving server.

          +---------------------------+
          |    ncid2ncid on Fedora    |
          |                           |
RPi#1 ===>|sending server #1 (CID:)   |    +-----------------+  
          |                           |    |           (CID:)|===>Apple iPad  
          |   receiving server (+CID:)|===>| ncidd on Fedora |  
          |                           |    |           (CID:)|===>Android tablet  
RPi#2 ===>|sending server #2 (CID:)   |    +-----------------+  
          |                           |
          +---------------------------+

CLIENT IMPLEMENTATION

  • contain OUTLOG: text lines
  • contain BLKLOG: text lines
  • contain ENDLOG: text lines
  • contain MSGLOG: text lines
  • contain PIDLOG: text lines
  • contain NOTLOG: text lines

(New in API 1.3) All OPT: lines output by the server are for informational and troubleshooting purposes only. Clients can optionally make use of them by giving the user a way to display them. Otherwise, clients are not required to display them, do not need to take any action on them and can safely ignore them. See Feature Set 1 OPT: definition and Feature Set 1: Client Implementation for more information.

Optional Client-to-Module

The optional client module lines are the same as in Feature Set 1, except the call or message type list is expanded and includes the following:

Call or message types: BLK CID END HUP MSG NOT OUT PID WID

Feature Set 3: Client Job Support

A client can send a "job" to the server to control certain server features and/or to query/update certain server settings. As an example, a connected client can trigger the creation of an entry in ncidd.alias, or add a phone number to ncidd.blacklist, on-the-fly.

The majority of the Client Jobs sent by a client are completed immediately by the server, and the server sends back the results. No further interaction between the client and server is needed.

The exceptions are the REQ: UPDATE and REQ: UPDATES Client Jobs (commands). These work by having the server create temporary copies of the call log(s) and then applying alias updates to them. The server sends back a summary to the user of what will be changed. The server is then free to accept the next set of Client Jobs from any connected client.

NOTE: The server does not support concurrent clients issuing the REQ: UPDATE and REQ: UPDATES Client Jobs. This is not enforced.

The temporary call log(s) remain in a limbo state until the server receives a WRK: <command> line type. When <command> indicates acceptance, the server removes the original call log(s) and replaces them with the temporary one(s). When <command> indicates rejection (cancellation), the server removes the temporary call log(s).

When you use Client Jobs, you need to keep in mind their effect on the state of the alias, blacklist and whitelist tables in the server's memory, and the effect on the current call log that may already be loaded by all connected clients.

OVERVIEW OF AVAILABLE CLIENT JOBS

Client Jobs are initiated when clients send REQ: line types to the server. The general format is:

REQ: <command> [<arguments>]

When an already-initiated Client Job requires additional information from the user, the client will send WRK: line types to the server. The general format is:

WRK: <command> <arguments>

The table below briefly describes each of the REQ: and WRK: commands.

Commands and arguments are case sensitive.

Clicking on the Job Request will show examples of the Client/Server exchanges.

Clicking on the (client) or (server) links in the table below will take you to more detailed information.

Job Request Description
REQ: alias <add|modify|remove> (client) (server) Manipulate entries in alias file
REQ: black <add|remove> (client) (server) Manipulate entries in blacklist file
REQ: white <add|remove> (client) (server) Manipulate entries in whitelist file
REQ: INFO <number>&&<name>
REQ: INFO <number>&&<name>&&<lineid>
(client) (server) Query alias, blacklist and whitelist status for a given number, name and/or lineid
REQ: RELOAD (client) (server) Force the NCID server to reload alias, blacklist and whitelist tables into the server's memory
REQ: REREAD (client) (server) Force the NCID server to resend the current call log to the client
REQ: UPDATE (client) (server) Temporarily update the current call log to process any alias changes. Changes are made permanent only if client responds with WRK: ACCEPT LOG.
REQ: UPDATES (client) (server) Temporarily update all call logs to process any alias changes. Changes are made permanent only if client responds with WRK: ACCEPT LOGS.
WRK: ACCEPT LOG (client) (server) Accept and make permanent the server's temporary updates to the current call log
WRK: REJECT LOG (client) (server) Reject (cancel) the server's temporary updates to the current call log
WRK: ACCEPT LOGS (client) (server) Accept and make permanent the server's temporary updates to all call logs
WRK: REJECT LOGS (client) (server) Reject (cancel) the server's temporary updates to all call logs

At a minimum, the Client Jobs needed to query and add an alias are as follows. Blacklist/whitelist queries and updates are similar.

Step Job Request What it does
1 REQ: INFO <number>&&<name> Check to see if an entry exists in alias/blacklist/whitelist
2 REQ: alias <add> <arguments> Write a new entry to ncidd.alias
3 REQ: RELOAD Force the NCID server to reload the modified alias list
4 REQ: UPDATE | UPDATES Allow the user to preview the update to the call log(s)
5 WRK: ACCEPT LOG | LOGS User commits the update(s)
6 REQ: REREAD Force the server to resend the updated current call log to the client performing the update

SERVER IMPLEMENTATION

  • modify the alias, blacklist, and whitelist files using the external ncidutil tool; return status
  • reload the alias file
  • reload the blacklist and whitelist files > (Removed in API 1.3) if the ncidd.conf::hangup option is being used
  • update the call log with new aliases using the external cidupdate tool; return results
  • resend the call log

Server Output Lines

The general structure of Server Output Lines consists of three line types: a start-of-server-data line, one or more lines of the server data, then an end-of-server-data line.

Each start-of-server-data line is paired with a specific end-of-server-data line as indicated below. For clarity, lines are indented to show their logical structure.

The contents of the INFO: and RESP: lines depend entirely on the Client Job being processed.

If a client sends a REQ: REREAD request ("resend call log"), the server will output line types 250 - 253, OPT: and 300 exactly as specified in Feature Set 1: Modem and Device Support. Their definitions are not included below.

The rest of this section contains the definitions of each server output line type for Client Jobs.

Start of data that the client should present to the user for acknowledgment. The data is in the form of one or more INFO: lines, and ends with 410.

(Added in API 1.2) Nothing is sent back to the server.

400 Start of data requiring an OK

Start of data that requires ACCEPT or REJECT from client (a client should follow up with an appropriate WRK: response). The data is in the form of one or more INFO: lines, and ends with 410.

401 Start of data requiring ACCEPT or REJECT

Start of data showing the output from the external ncidutil utility that is used to update the alias, blacklist and whitelist files. The data is in the form of one or more RESP: lines, and ends with 411.

402 Start of data showing status of handled request

When a Client Job is submitted, the server will validate the request and send back one or more INFO: lines to indicate what actions the client can do next, followed by an ending 411 line.

For example, a Client Job can request the status of a phone number, and as part of the server response there will be an indication as to whether the phone number is present or not in the blacklist. This tells the client making the request whether it can give the user the option to remove it from, or add it to, the blacklist.

403 Start of data defining permitted requests

End of data returned from server. Used to end 400 and 401 server messages:

410 End of data

End of response. Used to end 402 and 403 server messages:

411 End of response

The server will send an appropriate beginning 40x line, then one or more INFO: lines, and finally an ending 41x line.

The server outputs INFO: lines in one of two forms:

  • Free form text, with as many INFO: lines as needed.
  • A specific structure unique to REQ: INFO requests that indicates whether a name, number or lineid is present in the alias, blacklist and whitelist files. It will have a beginning 403 line, then the INFO: lines, and finally an ending 411 line. There are exactly two INFO: lines and they have the following general format:
  • First INFO: line contains alias status:

INFO: alias <number/name type> [<lineid type>]

where <number/name type> can be one of:

NOALIAS  | NMBRONLY | NAMEONLY | NMBRNAME | NMBRDEP  | NAMEDEP

and the optional <lineid type> can be one of:

NOALIAS  | LINEONLY

  • Second INFO: line contains blacklist and whitelist status:

INFO: <status>

where <status> can be one of:

neither      |
black name   | white name |
black number | white number

The server will send a 402 line, then one or more RESP: lines, and finally an ending 411 line.

The server sends one RESP: line for each line of output from the external ncidutil tool.

RESP: <a line from ncidutil>

CLIENT IMPLEMENTATION

If you want to implement a client to take advantage of Client Jobs:

(New in API 1.3) All OPT: lines output by the server are for informational and troubleshooting purposes only. Clients can optionally make use of them by giving the user a way to display them. Otherwise, clients are not required to display them, do not need to take any action on them and can safely ignore them. See Feature Set 1 OPT: definition and Feature Set 1: Client Implementation for more information.

A graphical NCID client will typically have the following features:

  • (Removed in API 1.3) only if the server sends OPT: hangup will the user have an option to force the server to reload the blacklist/whitelist files

Client-to-Server

Client Jobs are initiated when clients send REQ: line types to the server. The general format is:

  • REQ: <command> [<arguments>]

where <command> is one of the following:

alias | black | white | INFO | RELOAD | REREAD | UPDATE | UPDATES

When an already-initiated Client Job requires additional information from the user, the client will send WRK: line types to the server. The general format is:

  • WRK: <command> <arguments>

where <command> <arguments> is one of the following:

ACCEPT LOG | ACCEPT LOGS | REJECT LOG | REJECT LOGS

Commands and arguments are case sensitive.

The following Client Jobs are supported.

Add to alias list. A client would typically offer the user the option to add an item to the alias list if the INFO: alias line returned NOALIAS.

where:

  • number is from the call log
  • alias is input from the user
  • type is the alias type or NOALIAS if none
  • name is from the call log

Modify alias. A client would typically offer the user the option to modify an alias if the INFO: alias line did not return NOALIAS.

where:

  • number is from the call log
  • alias is new alias
  • type is the alias type or NOALIAS if none
  • name is from the call log

Modifying an alias and specifying a new alias of nothing (null) is the same as removing an existing alias.

Remove alias. A client would typically offer the user the option to modify an alias if the INFO: alias line did not return NOALIAS.

where:

  • number is from the call log
  • type is the alias type or NOALIAS if none
  • name is from the call log

Add an item to the blacklist. Item is the name or number from the call log file. A client would typically offer the user the option to add an item to the black list if the INFO: response line was INFO: neither.

(Removed in API 1.1) The server must have sent, and the client must have received, OPT: hangup to enable this Client Job.

Remove from black list. Item is the name or number from the call log file. A client would typically offer the user the option to remove an item from the black list if the INFO: response was either INFO: black name or INFO: black number.

(Removed in API 1.1) The server must have sent, and the client must have received, OPT: hangup to enable this Client Job.

Add to white list. Item is the name or number from the call log file. A client would typically offer the user the option to add an item to the white list if the INFO: response line was INFO: neither.

(Removed in API 1.1) The server must have sent, and the client must have received, OPT: hangup to enable this Client Job.

Remove from white list. Item is the name or number from the call log file. A client would typically offer the user the option to remove an item from the white list if the INFO: response line was either INFO: white name or INFO: white number.

(Removed in API 1.1) The server must have sent, and the client must have received, OPT: hangup to enable this Client Job.

Request the status of alias, blacklist, and whitelist for a given number, name, and optional lineid. The name, number, and lineid must match exactly to retrieve the status. To retrieve whitelist and blacklist status, either name, number, or both name and number can match the blacklist or whitelist entry (i.e. both name and number do not have to match, but one of them must match). The number, name, and optional lineid are separated by &&.

The server responds with two INFO: lines that have the following general format:

  • First INFO: line contains alias status:

INFO: alias <number/name type> [<lineid type>]

where <number/name type> can be one of:

NOALIAS  | NMBRONLY | NAMEONLY | NMBRNAME | NMBRDEP  | NAMEDEP

and the optional <lineid type> can be one of:

NOALIAS  | LINEONLY

  • Second INFO: line contains blacklist and whitelist status:

INFO: <status>

where <status> can be one of:

neither      |
black name   | white name |
black number | white number

Reload alias, blacklist, and whitelist files.

(Removed in API 1.3) (the blacklist and whitelist files will not be reloaded unless the server OPT: hangup option is received)

Request that the server resend the call log. It is only sent to the client issuing REQ: REREAD. The server responds with line types 250 - 253, OPT: and 300 exactly as specified in Feature Set 1: Modem and Device Support.

Make a temporary copy of the current call log to process any alias changes. This executes the external cidupdate tool. See also Note 1 and Note 2 below.

Make temporary copies of all call logs to process any alias changes. This executes the external cidupdate tool. See also Note 1 and Note 2 below.

The user has indicated that changes to the current call log by REQ: UPDATE have been accepted. This causes the original call log to be removed and replaced with the temporary call log. See also Note 1 and Note 2 below.

The user has indicated that changes to the current call log by REQ: UPDATE have been rejected. This causes the temporary call log to be removed and no permanent updates take place. See also Note 1 below.

The user has indicated that changes to all call logs by REQ: UPDATES have been accepted. This causes the original call logs to be removed and replaced with the temporary call logs. See also Note 1 and Note 2 below.

The user has indicated that changes to all call logs by REQ: UPDATES have been rejected. This causes the temporary call logs to be removed and no permanent updates take place. See also Note 1 below.

Note 1: Clients are responsible for keeping track of pending call log updates initiated by REQ: UPDATE | UPDATES. The temporary call logs will remain on the server indefinitely until a client sends a WRK: command.

Note 2: The cidupdate tool preserves the date/time stamp of the original call log(s) when replacing them with the temporary log(s).

CLIENT JOB EXAMPLES

Clicking on the Job Request will show examples of the Client/Server exchanges.

Clicking on the (client) or (server) links in the table below will take you to more detailed information.

Job Request Description
REQ: alias <add|modify|remove> (client) (server) Manipulate entries in alias file
REQ: black <add|remove> (client) (server) Manipulate entries in blacklist file
REQ: white <add|remove> (client) (server) Manipulate entries in whitelist file
REQ: INFO <number>&&<name>
REQ: INFO <number>&&<name>&&<lineid>
(client) (server) Query alias, blacklist and whitelist status for a given number, name and/or lineid
REQ: RELOAD (client) (server) Force the NCID server to reload alias, blacklist and whitelist tables into the server's memory
REQ: REREAD (client) (server) Force the NCID server to resend the current call log to the client
REQ: UPDATE (client) (server) Temporarily update the current call log to process any alias changes. Changes are made permanent only if client responds with WRK: ACCEPT LOG.
REQ: UPDATES (client) (server) Temporarily update all call logs to process any alias changes. Changes are made permanent only if client responds with WRK: ACCEPT LOGS.
WRK: ACCEPT LOG (client) (server) Accept and make permanent the server's temporary updates to the current call log
WRK: REJECT LOG (client) (server) Reject (cancel) the server's temporary updates to the current call log
WRK: ACCEPT LOGS (client) (server) Accept and make permanent the server's temporary updates to all call logs
WRK: REJECT LOGS (client) (server) Reject (cancel) the server's temporary updates to all call logs

Below are examples of the Client/Server exchanges for Job Requests.

REQ: and WRK: lines are generated by the client. For readability, server responses are indented and long lines split using the "" continuation character. For brevity, the full paths to ncidutil, cidupdate, ncidd.alias, ncidd.blacklist, ncidd.whitelist and ncidd.conf::cidlog have been removed.

The majority of the alias examples use the NAMEDEP type ("change the name depending on the phone number") since it is most widely used.

  • First check to see if there is already an alias on file....
REQ: INFO 4075551212&&WIRELESS

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: neither
     411 End of response
  • We got alias NOALIAS so add it....
REQ: alias add "4075551212&&John on Cell" "NAMEDEP&&WIRELESS"

     ncidutil --ignore1                                    \
              --multi "ncidd.blacklist ncidd.whitelist"    \
              "ncidd.alias" Alias add                      \
              "4075551212&&John on Cell"                   \
              "NAMEDEP&&WIRELESS" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified:  ncidd.alias
         RESP:    added: alias NAME * = "John on Cell" if 4075551212
         RESP: Done.
     411 End of response
  • Modify it....
REQ: alias modify "4075551212&&John's iPhone" "NAMEDEP&&John on Cell"

     ncidutil --ignore1                                     \
              --multi "ncidd.blacklist ncidd.whitelist"     \
              "ncidd.alias" Alias modify                    \
              "4075551212&&John's iPhone"                   \
              "NAMEDEP&&John on Cell" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.alias
         RESP:     from: alias NAME * = "John on Cell" if "4075551212"
         RESP:       to: alias NAME * = "John's iPhone" if "4075551212"
         RESP: Done.
     411 End of response
  • Remove it....
REQ: alias remove "4075551212&&" "NAMEDEP&&John's iPhone"

     ncidutil --ignore1                                     \
              --multi "ncidd.blacklist ncidd.whitelist"     \
              "ncidd.alias" Alias remove                    \
              "4075551212&&" "NAMEDEP&&John's iPhone" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.alias
         RESP:  removed: alias NAME * = "John's iPhone" if "4075551212"
         RESP: Done.
     411 End of response

Note that the following are equivalent and are treated as "alias remove" because the new "...&&<alias>" is null. > REQ: alias modify "4075551212&&" "NAMEDEP&&John's iPhone" > REQ: alias remove "4075551212&&" "NAMEDEP&&John's iPhone"

  • First check to see if there is already a blacklist entry on file....
REQ: INFO 4075551212&&WIRELESS

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: neither
     411 End of response
  • We got neither (i.e., not in blacklist nor whitelist) so add it to blacklist based on the number and without a comment....
REQ: black add "4075551212" ""

     ncidutil "ncidd.blacklist" Blacklist add "4075551212" "" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.blacklist
         RESP:    added: 4075551212
         RESP: Done.
     411 End of response
  • Client sends REQ: RELOAD (not shown) to force server to update the table in the server's memory.

  • Query the status....

REQ: INFO 4075551212&&WIRELESS

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: black number
     411 End of response
  • We got black number as expected.

  • Remove it...

REQ: black remove "4075551212" ""

     ncidutil "ncidd.blacklist" Blacklist remove "4075551212" "" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.blacklist
         RESP:  removed: 4075551212
         RESP: Done.
     411 End of response
  • Other miscellaneous examples that assume the blacklist file is empty and that a REQ: RELOAD (not shown) is done between updates....

  • Add a new blacklisted number with a comment....

REQ: black add "4075551212" "imposter!"

     ncidutil "ncidd.blacklist" Blacklist add "4075551212" "imposter!" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.blacklist
         RESP:    added: 4075551212 # imposter!
         RESP: Done.
     411 End of response
  • Add a new blacklisted name with comment, then request status and notice black name in the response....
REQ: black add "WIRELESS" "telemarketer"

     ncidutil "ncidd.blacklist" Blacklist add "WIRELESS" "telemarketer" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.blacklist
         RESP:    added: WIRELESS # telemarketer
         RESP: Done.
     411 End of response

REQ: RELOAD

     (server responses not shown)
     
REQ: INFO 4075551212&&WIRELESS

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: black name
     411 End of response
  • Add a new blacklisted number with a match name....
REQ: black add "4075551212" "=Fax machine keeps calling"

     ncidutil "ncidd.blacklist" Blacklist add "4075551212"  \
              "=Fax machine keeps calling" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.blacklist
         RESP:    added: 4075551212 #=Fax machine keeps calling
         RESP: Done.
     411 End of response
  • For the purpose of this example, before adding whitelist entries we'll create a blacklist entry to cover the entire area code 407 and include an appropriate comment...
REQ: black add "^407" "blacklist all numbers in area code 407"

     ncidutil "ncidd.blacklist" Blacklist add "^407"         \
              "blacklist all numbers in area code 407" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.blacklist
         RESP:    added: ^407 # blacklist all numbers in area code 407
         RESP: Done.
     411 End of response
  • Client sends REQ: RELOAD (not shown) to force server to update the table in the server's memory.

  • Check the status on two different phone numbers in area code 407...

REQ: INFO 4075551212&&ORLANDO, FL

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: black number
     411 End of response

REQ: INFO 4072221515&&TOLL FREE

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: black number
     411 End of response>>>
  • We got black number as expected on both numbers. Add the first one to the whitelist based on the number and without a comment....
REQ: white add "4075551212" ""

     ncidutil "ncidd.whitelist" Whitelist add "4075551212" "" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.whitelist
         RESP:    added: 4075551212
         RESP: Done.
     411 End of response

REQ: RELOAD

     (server responses not shown)
     
  • Check the status on the numbers again...
REQ: INFO 4075551212&&ORLANDO, FL

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: white number
     411 End of response
REQ: INFO 4072221515&&TOLL FREE

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: black number
     411 End of response
  • As expected, we got white number on the first one and black number on the second.

  • Remove it...

REQ: white remove "4075551212" ""

     ncidutil "ncidd.whitelist" Whitelist remove "4075551212" "" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.whitelist
         RESP:  removed: 4075551212
         RESP: Done.
     411 End of response
  • Other miscellaneous examples that assume the whitelist file is empty and that a REQ: RELOAD (not shown) is done between updates....
  • Add a new whitelisted number with a comment....
REQ: white add "4075551212" "Lottery Commission"

     ncidutil "ncidd.whitelist" Whitelist add "4075551212"   \
              "Lottery Commission" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.whitelist
         RESP:    added: 4075551212 # Lottery Commission
         RESP: Done.
     411 End of response
  • Add a new whitelisted name with comment, then request status and notice white name in the response....
REQ: white add "ORLANDO, FL" "Chamber of Commerce"

     ncidutil "ncidd.whitelist" Whitelist add "ORLANDO, FL"  \
              "Chamber of Commerce" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.whitelist
         RESP:    added: "ORLANDO, FL" # Chamber of Commerce
         RESP: Done.
     411 End of response

REQ: RELOAD

     (server responses not shown)
     
REQ: INFO 4075551212&&ORLANDO, FL

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: white name
     411 End of response
  • Add a new whitelisted number with a match name....
REQ: white add "4075551212" "=Walt Disney World"

     ncidutil "ncidd.whitelist" Whitelist add "4075551212"   \
              "=Walt Disney World" 2>&1
     402 Start of data showing status of handled request
         RESP: Modified: ncidd.whitelist
         RESP:    added: 4075551212 #=Walt Disney World
         RESP: Done.
     411 End of response
  • This number and name have no alias, blacklist or whitelist entry...
REQ: INFO 4075551212&&WIRELESS

     403 Start of data defining permitted requests
         INFO: alias NOALIAS
         INFO: neither
     411 End of response
  • Same as above, except there's also no alias for <lineid> of HOME....
REQ: INFO 4075551212&&WIRELESS&&HOME

     403 Start of data defining permitted requests
         INFO: alias NOALIAS NOALIAS 
         INFO: neither
     411 End of response
  • An example showing blacklist and white list entries, and aliases based on the number and lineid. The whitelist entry takes precedence over the blacklist of the entire area code; this is why REQ: INFO doesn't report black number. For clarity, some server responses to REQ: RELOAD are not shown....
REQ: RELOAD

     400 Start of data requiring OK
     
         INFO: Alias Table:
         INFO:     Number of Entries: 2
         INFO:     SLOT TYPE     FROM TO           DEPEND
         INFO:     ---- ----     ---- --           ------
         INFO:     000  NAMEDEP  *    John on Cell "4075551212"
         INFO:     001  LINEONLY HOME CELL         
         
         INFO: Blacklist Table:
         INFO:     Number of Entries: 1
         INFO:     SLOT ENTRY  MATCH NAME
         INFO:     ---- -----  ----------
         INFO:     000  "^407" 
         
         INFO: Whitelist Table:
         INFO:     Number of Entries: 1
         INFO:     SLOT ENTRY        MATCH NAME
         INFO:     ---- -----        ----------
         INFO:     000  "4075551212" 
         
     410 End of data

REQ: INFO 4075551212&&WIRELESS

     403 Start of data defining permitted requests
         INFO: alias NAMEDEP
         INFO: white number
     411 End of response

REQ: INFO 4075551212&&WIRELESS&&HOME

     403 Start of data defining permitted requests
         INFO: alias NAMEDEP LINEONLY 
         INFO: white number
     411 End of response
  • Force the NCID server to reload alias, blacklist and whitelist tables from their respective disk files into the server's memory:
REQ: RELOAD

     400 Start of data requiring OK
         INFO: Received Signal 1: Hangup: 1
         INFO: Reloading alias, blacklist, and whitelist files
         INFO: Processed alias file: ncidd.alias
         INFO: Alias Table:
         INFO:     Number of Entries: 6
         INFO:     SLOT TYPE     FROM        TO           DEPEND
         INFO:     ---- ----     ----        --           ------
         INFO:     000  NAMEDEP  *           John on Cell "4075551212"
         INFO:     001  LINEONLY HOME        CELL         
         INFO:     002  NMBRONLY 6768048218  Caleb Vinson
         INFO:     003  NAMEONLY TOLL FREE   TELEMARKETER
         INFO:     004  NMBRNAME OUT-OF-AREA UNAVAILABLE
         INFO:     005  NMBRDEP  *           4075551212   "SMITH JEFF"
         INFO: Processed blacklist file: ncidd.blacklist
         INFO: Blacklist Table:
         INFO:     Number of Entries: 18
         INFO:     SLOT ENTRY        MATCH NAME
         INFO:     ---- -----        ----------
         INFO:     000  "^407" 
         INFO:     001  "9075551414" "Fax machine keeps calling"
         INFO:     002  "2133750923" "FCC bad list 2015-12-14"
         INFO:     003  "2133750992" "FCC bad list 2015-12-14"
         INFO:     004  "2134150180" "FCC bad list 2015-12-14"
         INFO:     005  "2134566756" "FCC bad list 2015-12-14"
         INFO:     006  "2134771084" "FCC bad list 2015-12-14"
         INFO:     007  "2134879500" "FCC bad list 2015-12-14"
         INFO:     008  "2135038127" "FCC bad list 2015-12-14"
         INFO:     009  "2139227973" "FCC bad list 2015-12-14"
         INFO:     010  "2139925914" "FCC bad list 2015-12-14"
         INFO:     011  "2139925916" "FCC bad list 2015-12-14"
         INFO:     012  "2139925922" "FCC bad list 2015-12-14"
         INFO:     013  "2142284484" "FCC bad list 2015-12-14"
         INFO:     014  "2142388242" "FCC bad list 2015-12-14"
         INFO:     015  "2142694345" "FCC bad list 2015-12-14"
         INFO:     016  "2142698811" "FCC bad list 2015-12-14"
         INFO:     017  "2142815189" "FCC bad list 2015-12-14"
         INFO: Processed whitelist file: ncidd.whitelist
         INFO: Whitelist Table:
         INFO:     Number of Entries: 3
         INFO:     SLOT ENTRY        MATCH NAME
         INFO:     ---- -----        ----------
         INFO:     000  "4075551212" 
         INFO:     001  "4074441992" "Walt Disney World"
         INFO:     002  "ORLANDO, FL"
         INFO: Reloaded alias, blacklist, and whitelist files
     410 End of data
  • Force the server to resend the call log and OPT: lines to the client, and if the call log is not empty....
REQ: REREAD

         CIDLOG: *DATE*12012015*TIME*0028*LINE*HOME*\
                 NMBR*2956237064*MESG*NONE*NAME*Minnie Wallace*
         HUPLOG: *DATE*12012015*TIME*0105*LINE*HOME*\
                 NMBR*2786279268*MESG*NONE*NAME*Sophie Reyes*
         ...  
     250 End of call log
     OPT: hangup-1  
     OPT: ...  
     300 End of connection startup
  • Force the server to resend the call log and OPT: lines to the client, but if the server is not configured to send the call log....
REQ: REREAD

     251 Call log not sent
     OPT: hangup-1  
     OPT: ...  
     300 End of connection startup
  • Force the server to resend the call log and OPT: lines to the client, but if the call log is empty....
REQ: REREAD

     252 Call log empty
     OPT: hangup-1  
     OPT: ...  
     300 End of connection startup
  • Force the server to resend the call log and OPT: lines to the client, but if the call log file does not exist...
REQ: REREAD

     253 No Call log
     OPT: hangup-1  
     OPT: ...  
     300 End of connection startup
  • Update the current call log file with the latest alias changes, store the changes temporarily, and present a summary for the user to accept or reject....
REQ: UPDATE

     cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\
               < /dev/null 2>&1
     401 Start of data requiring ACCEPT or REJECT
         INFO: There was 1 change to cidcall.log
         INFO: 
         INFO: (NAMEDEP) Changed "John on Cell" to           \
               "John's iPhone" for 4075551212 1 time
     410 End of data
  • If no changes were found, let the user know and do not prompt to accept or reject....
REQ: UPDATE

     cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\
               < /dev/null 2>&1
     400 Start of data requiring OK
         INFO: There were no changes to cidcall.log
     410 End of data
  • Update all call log files with the latest alias changes, store the changes temporarily, and present a summary for the user to accept or reject....
REQ: UPDATES

     cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\
               --multi --ignore1 < /dev/null 2>&1
     401 Start of data requiring ACCEPT or REJECT
         INFO: There were 2 changes to cidcall.log
         INFO: There were 224 changes to cidcall.log.1
         INFO: There were 14 cidcall.log.2
         INFO: There were 18 cidcall.log.3
         INFO: There were 24 cidcall.log.4
         INFO: There were 16 cidcall.log.5
         INFO: 
         INFO: (NAMEDEP) Changed "John on Cell" to           \
               "John's iPhone" for 4075551212 298 times
     410 End of data
  • If no changes were found, let the user know and do not prompt to accept or reject....
REQ: UPDATES

     cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\
               --multi < /dev/null 2>&1
     400 Start of data requiring OK
         INFO: There were no changes to cidcall.log
     410 End of data
  • Alias changes have been applied to a temporary copy of the current call log file, and the user has accepted the changes. This causes the server to replace the current call log file with the temporary copy. No further interaction with the user is needed.
REQ: UPDATE

     cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\
               < /dev/null 2>&1
     401 Start of data requiring ACCEPT or REJECT
         INFO: There was 1 change to cidcall.log
         INFO: 
         INFO: (NAMEDEP) Changed "John on Cell" to           \
               "John's iPhone" for 4075551212 1 time
     410 End of data
     
WRK: ACCEPT LOG

     mv cidcall.log.new cidcall.log
  • Alias changes have been applied to a temporary copy of the current call log file, and the user has rejected the changes. This causes the server to remove the temporary copy of the current call log file. No further interaction with the user is needed.
REQ: UPDATE

     cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\
               < /dev/null 2>&1
     401 Start of data requiring ACCEPT or REJECT
         INFO: There was 1 change to cidcall.log
         INFO: 
         INFO: (NAMEDEP) Changed "John on Cell" to           \
               "John's iPhone" for 4075551212 1 time
     410 End of data
     
WRK: REJECT LOG

     rm cidcall.log.new
  • Alias changes have been applied to temporary copies of all call log files, and the user has accepted the changes. This causes the server to replace the existing call log files with the temporary copies. No further interaction with the user is needed.
REQ: UPDATES

     cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\
               --multi --ignore1 < /dev/null 2>&1
     401 Start of data requiring ACCEPT or REJECT
         INFO: There were 2 changes to cidcall.log
         INFO: There were 224 changes to cidcall.log.1
         INFO: There were 14 cidcall.log.2
         INFO: There were 18 cidcall.log.3
         INFO: There were 24 cidcall.log.4
         INFO: There were 16 cidcall.log.5
         INFO: 
         INFO: (NAMEDEP) Changed "John on Cell" to           \
               "John's iPhone" for 4075551212 298 times
     410 End of data
     
WRK: ACCEPT LOGS

     for f in cidcall.log.*[0-9]; do mv $f.new $f; done
     mv cidcall.log.new cidcall.log
  • Alias changes have been applied to temporary copies of all call log files, and the user has rejected the changes. This causes the server to remove the temporary copies of all call log files. No further interaction with the user is needed.
REQ: UPDATES

     cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\
               --multi --ignore1 < /dev/null 2>&1
     401 Start of data requiring ACCEPT or REJECT
         INFO: There were 2 changes to cidcall.log
         INFO: There were 224 changes to cidcall.log.1
         INFO: There were 14 cidcall.log.2
         INFO: There were 18 cidcall.log.3
         INFO: There were 24 cidcall.log.4
         INFO: There were 16 cidcall.log.5
         INFO: 
         INFO: (NAMEDEP) Changed "John on Cell" to           \
               "John's iPhone" for 4075551212 298 times
     410 End of data
     
WRK: REJECT LOGS

     rm cidcall.log.*.new
     rm cidcall.log.new

Feature Set 4: Acknowledgment Support

You might want to implement this feature set if the network connection between a client and the server suffers from reliability issues.

A client can ask the server to ACK(nowledge) all lines sent to it.

A client can also ask the server to respond to a YO request to make sure the communication to the server is still there.

SERVER IMPLEMENTATION

If you want to implement a server to take advantage of acknowledgments:

Server Output Lines

The server response to a REQ: YO line.

ACK: REQ: YO

The server response to a REQ: ACK, CALL:, CALLINFO:, or NOT: line. The ACK includes the received line. See the gateway section for more information. Requires a Feature Set 2 server.

Examples:

ACK: REQ: ACK
ACK: PID: ###DATE...
ACK: NOT: <message>
ACK: CALLINFO: ###END ...

GATEWAY IMPLEMENTATION

Gateway-to-Server

A request to the server for an ACK to make sure communication with the server is active.

REQ: YO

A request for an ACK on each line sent to the server. Normally an ACK is only required for client/gateway combinations on a smartphone. It is used to verify the PID: and NOT: lines were received by the server. Requires a Feature Set 2 server.

REQ: ACK

CLIENT IMPLEMENTATION

Client-to-Server

A request to the server for an ACK to make sure communication with the server is active.

REQ: YO

Feature Set 5: Relay Job Support (new in API 1.4)

Relay Jobs allow clients and gateways to query and control other clients and gateways. Compare this with Feature Set 3 Client Jobs where clients query and/or control only the server, e.g., adding new numbers to ncidd.blacklist.

RELAY JOB OVERVIEW

Relay Jobs were originally conceived as a way for NCIDpop to ask a user for an SMS phone number and an SMS text message to be sent using NCID Android running on a smartphone. With the NOT: line type, smartphones could already forward SMS messages to connected NCID clients -- one direction only. Relay Jobs allow NCID clients like NCIDpop to "remotely" create new SMS messages for sending via smartphones. (See Appendix E: SMS Relay Job sequence diagram.)

After the initial SMS design, the Relay Job concept was expanded to allow querying the status of certain smartphone properties (e.g., battery level), and to control the smartphone's behavior in limited ways (e.g., dial a phone number).

With the final design described below, Relay Jobs are no longer limited to querying/controlling smartphones; the Relay Job specification is now generic enough that other clients and gateways can be queried/controlled.

A Relay Job consists of three primary pieces of information:

RJO and RJT device names should be unique (this is not strictly enforced) and are normally configured manually by the user within the NCID client or gateway program. (Quite often the RJT name will be the same value used to populate the LINE*<lineid> field pair for non-RLY: line types.) If there is no way for the user to set the device name, or it's deemed unnecessary, then the default device name is usually the output of the hostname program on Unix/Linux, or the Computer name under Windows. When the NCID server sends the Relay Job to all listening clients and gateways, each client/gateway compares its device name against the RJT. A special target of '@all' is allowed and, assuming the target can execute the Relay Job command, any and all appropriate targets will carry it out.

What queries/actions are allowed is entirely up to the capability of the RJT. (For example, a wifi-only tablet would not be able to dial a phone number but its battery level could probably be queried.) For this reason, this API document can only suggest possible commands that could be used; the NCID server doesn't care what they are.

If a target is not enabled for Relay Jobs, or if it is enabled but is unable to execute the Relay Job command (e.g., the wifi-only tablet can't dial a number), then the target will simply ignore the Relay Job.

The NCID server's only role is to be the middle man and "relay" these jobs from an RJO to all listening clients and gateways.

SERVER IMPLEMENTATION

If you want to implement a server to handle Relay Jobs:

RELAY JOB ORIGIN (RJO) IMPLEMENTATION

An RJO is typically considered to be a client and not a gateway because clients interact with a user. However, gateways can also be RJOs.

If you want to implement a client or gateway to initiate Relay Jobs:

RJO Line Type Definition

A Relay Job sent to the server.

RLY: <message> ###DATE*<date>*TIME*<time>*TO*<target>*FROM*<origin>*CMD*<command>*

RLY: <message> ###DATE*<date>*TIME*<time>*TO*<target>*FROM*<origin>*CMD*<command>*ARG1*<arg1>*

RLY: <message> ###DATE*<date>*TIME*<time>*TO*<target>*FROM*<origin>*CMD*<command>*ARG1*<arg1>*ARG2*<arg2>*...

<message> is optional and depends on <command>.

(New in API 1.4) A +RLY: line is the same as RLY: except the leading "+" indicates it is coming from a Forwarding Gateway.

The RLY: line has the following field pairs (field label and field data):

<label>*<data>* Description
### start of the information part of the message being sent to the server
DATE*date* where date is mmddyyyy or ddmmyyyy, m = month, d = day, y = year
TIME*time* where time is hhmm in 24-hour format, h = hour, m = minute
TO*target* where target is a case-sensitive string of characters or '@all'
FROM*origin* where origin is a case-sensitive string of characters
CMD*command* where command is a case-sensitive string of characters
ARG1*arg1* optional field pair where arg1 is a string of characters
ARG2*arg2* optional field pair where arg2 is a string of characters
... ...
ARGx*argx* optional field pair where argx is a string of characters

The following are some suggestions for <command>:

<command> <arg1> Description
BATTERY reply with the battery level in a NOT:
LOCATION reply with the GPS location in a NOT:
PLACECALL <phone number> remotely dial <phone number>
RINGTONE play the default ringtone to help find the smartphone, or just to annoy someone
TEXTMSG <phone number> send an SMS <message> to <phone number>

When the server sends the call log, it replaces the RLY: label with RLYLOG:.

RELAY JOB TARGET (RJT) IMPLEMENTATION

An RJT is typically considered to be a gateway and not a client because gateways usually do not interact with a user. However, clients can also be RJTs.

If you want to implement a client or gateway to take action on Relay Jobs:

RJT Line Type Definition

A Relay Job sent to all listening clients and gateways. It is the same as the RJO Line Type Definition except instead of ### before the first field pair, the server changes it to ***.

(New in API 1.4) A +RLY: line is the same as RLY: except the leading "+" indicates it is coming from a Forwarding Gateway.

RELAY JOB EXAMPLES

The following examples are based on a setup with four devices:

CMD*BATTERY*
Program Device Entry in ncidd.log
NCIDpop Winny RLY: ###DATE*09052016*TIME*0111*TO*Tabby*FROM*Winny*CMD*BATTERY*
ncidd CrayWannaBe RLY: ***DATE*09052016*TIME*0111*TO*Tabby*FROM*Winny*CMD*BATTERY*
NCID Android Tabby NOT: Battery is 100.0% (Full) ###DATE*09052016*TIME*0111*NAME*-*NMBR*-*LINE*Tabby*MTYPE*IN*
ncidd CrayWannaBe NOT: Battery is 100.0% (Full) ***DATE*09052016*TIME*0111*NAME*-*NMBR*-*LINE*Tabby*MTYPE*IN*
Program Device Entry in ncidd.log
NCIDpop Winny RLY: ###DATE*09052016*TIME*0111*TO*@all*FROM*Winny*CMD*BATTERY*
ncidd CrayWannaBe RLY: ***DATE*09052016*TIME*0111*TO*@all*FROM*Winny*CMD*BATTERY*
NCID Android Tabby NOT: Battery is 100.0% (Full) ###DATE*09052016*TIME*0111*NAME*-*NMBR*-*LINE*Tabby*MTYPE*IN*
ncidd CrayWannaBe NOT: Battery is 100.0% (Full) ***DATE*09052016*TIME*0111*NAME*-*NMBR*-*LINE*Tabby*MTYPE*IN*
NCID Android Smarty NOT: Battery is 84.0% (Discharging) ###DATE*09052016*TIME*0111*NAME*-*NMBR*-*LINE*Smarty*MTYPE*IN*
ncidd CrayWannaBe NOT: Battery is 84.0% (Discharging) ***DATE*09052016*TIME*0111*NAME*-*NMBR*-*LINE*Smarty*MTYPE*IN*
CMD*LOCATION*
Program Device Entry in ncidd.log
NCIDpop Winny RLY: ###DATE*09052016*TIME*1330*TO*Smarty*FROM*Winny*CMD*LOCATION*
ncidd CrayWannaBe RLY: ***DATE*09052016*TIME*1330*TO*Smarty*FROM*Winny*CMD*LOCATION*
NCID Android Smarty NOT: Location is: latitude 45.57175012, longitude -122.67063299 ###DATE*09052016*TIME*1330*NAME*-*NMBR*-*LINE*Smarty*MTYPE*IN*
ncidd CrayWannaBe NOT: Location is: latitude 45.57175012, longitude -122.67063299 ***DATE*09052016*TIME*1330*NAME*-*NMBR*-*LINE*Smarty*MTYPE*IN*
CMD*PLACECALL*
Program Device Entry in ncidd.log
NCIDpop Winny RLY: ###DATE*09052016*TIME*1751*TO*Smarty*FROM*Winny*CMD*PLACECALL*ARG1*4075557777*
ncidd CrayWannaBe RLY: ***DATE*09052016*TIME*1751*TO*Smarty*FROM*Winny*CMD*PLACECALL*ARG1*4075557777*
NCID Android Smarty CALL: ###DATE09061751...CALLOUT...LINESmarty...NMBR4075557777...NAMEJOHN ON CELL+++
ncidd CrayWannaBe OUT: *DATE*09062016*TIME*1751*LINE*Smarty*NMBR*4075557777*MESG*NONE*NAME*JOHN ON CELL*
NCID Android Smarty CALLINFO: ###BYE...DATE09061751...SCALL09/06/2016 17:51:12...ECALL09/06/2016 17:58:09...CALLOUT...LINESmarty...NMBR4075557777...NAMEJOHN ON CELL+++
ncidd CrayWannaBe END: *HTYPE*BYE*DATE*09062016*TIME*1751*SCALL*09/06/2016 17:51:12*ECALL*09/06/2016 17:58:09*CTYPE*OUT*LINE*Smarty*NMBR*4075557777*NAME*JOHN ON CELL*
CMD*RINGTONE*
Program Device Entry in ncidd.log
NCIDpop Winny RLY: ###DATE*09052016*TIME*1241*TO*Smarty*FROM*Winny*CMD*RINGTONE*
ncidd CrayWannaBe RLY: ***DATE*09052016*TIME*1241*TO*Smarty*FROM*Winny*CMD*RINGTONE*
CMD*TEXTMSG*
Program Device Entry in ncidd.log
NCIDpop Winny RLY: Are you coming over to see the surprise eclipse tonight?###DATE*09052016*TIME*2138*TO*Smarty*FROM*Winny*CMD*TEXTMSG*ARG1*4075557777*
ncidd CrayWannaBe RLY: Are you coming over to see the surprise eclipse tonight?***DATE*09052016*TIME*2138*TO*Smarty*FROM*Winny*CMD*TEXTMSG*ARG1*4075557777*
NCID Android Smarty NOT:Are you coming over to see the surprise eclipse tonight?###DATE*09062016*TIME*2138*NAME*JOHN ON CELL*NMBR*14075557777*LINE*Smarty*MTYPE*OUT*
ncidd CrayWannaBe NOT:Are you coming over to see the surprise eclipse tonight?***DATE*09062016*TIME*2138*NAME*JOHN ON CELL*NMBR*14075557777*LINE*Smarty*MTYPE*OUT*

Sending a Text Message

The server accepts a single line text message from a client and broadcasts it to all connected clients. All messages must begin with the MSG: label.

Other programs such as netcat can be used to send a message. Telnet is not recommended. If netcat is used, please note there are different versions with different options.

This shell script example creates a 10 minute food timer. The -w1 is a one second idle timeout to wait before disconnect:

sleep 600; echo "MSG: Food Ready" | nc -w1 localhost 3333 > /dev/null

Country Codes

Country codes tell the client how to display the telephone number, especially when the area code and number each have a varying number of digits. The Country Codes supported in the client are shown in the table below. The NONE country code leaves the number unformatted. Feel free to request more country codes.

See http://www.iso.org/iso/english_country_names_and_code_elements for the two letter country codes.

Country Country Code Area Code URL
NONE NONE
United States US https://en.wikipedia.org/wiki/North_American_Numbering_Plan
Sweden SE https://en.wikipedia.org/wiki/Telephone_numbers_in_Sweden#Area_codes
Germany DE https://en.wikipedia.org/wiki/Area_codes_in_Germany
United Kingdom UK https://en.wikipedia.org/wiki/United_Kingdom_area_codes
Croatia HR https://en.wikipedia.org/wiki/Telephone_numbers_in_Croatia

Emulation Programs and Test Files

The test directory in the NCID source contains emulation programs for the server, client, SIP gateway, and modem. There are also test files for the server and a client logfile used for screenshots in the source test directory. The README.test file explains how to use the emulation programs and test files.

Appendix A: Quick Reference List of all call type line identifiers

Arranged alphabetically.

Except for MSG:, +MSG:, NOT:, +NOT:, RLY: and +RLY: types which have two definitions, click on a Call Type to be taken to its complete definition.

# Call Type Function Description
1 BLK:  or +BLK: call Call blocked
2 CID:  or +CID: call Incoming call from modem or other input device
3 END:  or +END: call End of call with call accounting info
4 HUP:  or +HUP: call Call hangup
5 MSG:  or +MSG: text Text message, server output or client output
6 NOT:  or +NOT: text Text message from smartphone, server output or gateway output
7 OUT:  or +OUT: call Outgoing call
8 PID:  or +PID: call Incoming call from smartphone
9 RLY:  or +RLY: relay Relay Job (New in API 1.4), Relay Job Origin (RJO) or Relay Job Target (RJT)
10 WID:  or +WID: call Incoming call waiting Caller ID from modem or other input device

For development purposes, here are non-clickable, copy-and-paste friendly versions all on one line:

No colons:

Space delimited:
BLK CID END HUP MSG NOT OUT PID RLY WID

+BLK +CID +END +HUP +MSG +NOT +OUT +PID +RLY +WID

Comma delimited:
BLK,CID,END,HUP,MSG,NOT,OUT,PID,RLY,WID

+BLK,+CID,+END,+HUP,+MSG,+NOT,+OUT,+PID,+RLY,+WID

Comma and space delimited:
BLK, CID, END, HUP, MSG, NOT, OUT, PID, RLY, WID

+BLK, +CID, +END, +HUP, +MSG, +NOT, +OUT, +PID, +RLY, +WID

Pipe delimited:
BLK|CID|END|HUP|MSG|NOT|OUT|PID|RLY|WID

+BLK|+CID|+END|+HUP|+MSG|+NOT|+OUT|+PID|+RLY|+WID

Regex-ready, pipe delimited:
^BLK|^CID|^END|^HUP|^MSG|^NOT|^OUT|^PID|^RLY|^WID

^+BLK|^+CID|^+END|^+HUP|^+MSG|^+NOT|^+OUT|^+PID|^+RLY|^+WID

With colons:

Space delimited:
BLK: CID: END: HUP: MSG: NOT: OUT: PID: RLY: WID:

+BLK: +CID: +END: +HUP: +MSG: +NOT: +OUT: +PID: +RLY: +WID:

Comma delimited:
BLK:,CID:,END:,HUP:,MSG:,NOT:,OUT:,PID:,RLY:,WID:

+BLK:,+CID:,+END:,+HUP:,+MSG:,+NOT:,+OUT:,+PID:,+RLY:,+WID:

Comma and space delimited:
BLK:, CID:, END:, HUP:, MSG:, NOT:, OUT:, PID:, RLY:, WID:

+BLK:, +CID:, +END:, +HUP:, +MSG:, +NOT:, +OUT:, +PID:, +RLY:, +WID:

Pipe delimited:
BLK:|CID:|END:|HUP:|MSG:|NOT:|OUT:|PID:|RLY:|WID:

+BLK:|+CID:|+END:|+HUP:|+MSG:|+NOT:|+OUT:|+PID:|+RLY:|+WID:

Regex-ready, pipe delimited:
^BLK:|^CID:|^END:|^HUP:|^MSG:|^NOT:|^OUT:|^PID:|^RLY:|^WID:

^+BLK:|^+CID:|^+END:|^+HUP:|^+MSG:|^+NOT:|^+OUT:|^+PID:|^+RLY:|^+WID:

Appendix B: Index to all line type definitions

Arranged alphabetically.

\n (newline)
200
210
250 - 253
300
400
401
402
403
410
411
ACK:
BLK:  or +BLK:
BLKLOG:
CALL:
CALLINFO:
CID:  or +CID:
CIDINFO:  or +CIDINFO:
CIDLOG:
END:  or +END:
ENDLOG:
HUP:  or +HUP:
HUPLOG:
INFO:
LOG:
MSG:  or +MSG: (server)
MSG:  or +MSG: (client)
MSGLOG:
NOT:  or +NOT: (server)
NOT:  or +NOT: (gateway)
NOTLOG:
OPT:
OUT:  or +OUT:
OUTLOG:
PID:  or +PID:
PIDLOG:
REQ:
REQ: ACK
REQ: INFO <number>&&<name>
REQ: INFO

REQ: RELOAD
REQ: REREAD
REQ: UPDATE
REQ: UPDATES
REQ: YO (gateway)
REQ: YO (client)
REQ: alias
REQ: black
REQ: white
RESP:
RLY:  or +RLY: (Relay Job Origin (RJO)) (new in API 1.4)
RLY:  or +RLY: (Relay Job Target (RJT)) (new in API 1.4)
RLYLOG: (new in API 1.4)
WID:  or +WID:
WIDLOG:
WRK:
WRK: ACCEPT LOG
WRK: ACCEPT LOGS
WRK: REJECT LOG
WRK: REJECT LOGS

Appendix C: Quick Reference List of all server configuration settings

Arranged alphabetically by setting name.

File Name Setting name Brief description
ncidd.conf announce file name of raw modem device (.rmd) file to be played
ncidd.conf audiofmt "AT" command string to set voice modem audio format
ncidd.conf blacklist blacklist file name
ncidd.conf cidalias alias file name
ncidd.conf cidlog log file name for call activity
ncidd.conf cidlogmax maximum size in bytes of cidlog
ncidd.conf cidnoname enable/disable detection of caller ID name from Telco
ncidd.conf datalog log file name for raw data received from modems and gateways
ncidd.conf gencid enable/disable reporting of generic caller ID
ncidd.conf hangup disable/select hangup mode
ncidd.conf hupmode Hangup Extension: disable/select hangup mode
ncidd.conf hupname Hangup Extension: file name of external script/program
ncidd.conf huprmd Hangup Extension: file name of raw modem device (.rmd) file to be played
ncidd.conf ignore1 enable/disable leading 1 in US/Canada
ncidd.conf initcid "AT" command string to enable modem's caller ID
ncidd.conf initstr "AT" command string to initialize modem
ncidd.conf lineid phone line identifier
ncidd.conf lockfile full path to modem/serial device lock file
ncidd.conf nomodem enable/disable sending of "AT" command strings
ncidd.conf noserial enable/disable use of modem or serial device
ncidd.conf pickup enable/disable sending of "AT" command string to pickup phone line
ncidd.conf pidfile full path to server's process id file, prevents multiple instances
ncidd.conf port server's listening TCP/IP port number
ncidd.conf regex enable/disable regular expressions for alias, blacklist and whitelist files
ncidd.conf send cidinfo enable/disable sending of ring info to clients
ncidd.conf send cidlog enable/disable sending of call log to clients
ncidd.conf ttyclocal enable/disable hardware flow control for modem or serial device
ncidd.conf ttyport modem or serial device port name
ncidd.conf ttyspeed modem or serial device communication speed
ncidd.conf verbose verbose level
ncidd.conf whitelist blacklist file name

Appendix D: More info about modem MESG hexadecimal characters

When a modem receives something in the raw caller ID data stream that it does not understand, it will generate a MESG line followed by a series of hexadecimal characters. This does not mean an error was detected, rather it is additional call detail provided by the telco that the modem doesn't know how to decode.

The NMBR label may be DDN_NMBR (Dialable Directory Number) instead, depending on the country.

Example of an incoming call generated by British Telecom in the UK:

RING

MESG = 110101    
DATE = 0511    
TIME = 1852    
NAME = JOHN DOE   
NMBR = 4075550000 or DDN_NMBR = 4075550000    

RING

The hexadecimal characters can be interpreted by going to the British Telecom document index, accepting the copyright agreement, and then selecting Suppliers' Information Notes (SIN) #227. Page 22 of 34 has the following info (field names relabeled for clarity):

Field name Hex byte Meaning
Parameter Code 11 Call type
Parameter Length 01 1 byte
Qualifier 01 Voice call

This indicates a normal call so the MESG line can be safely ignored.

Example of a call from Bell Canada:

RING

DATE = 0511    
TIME = 1852    
NAME = JOHN DOE   
NMBR = 4075550000 or DDN_NMBR = 4075550000    
MESG = 06014C

RING

The hexadecimal characters can be interpreted using page 15 of 21 of the Bell Interface Document (BID), BID-0001:

Field name Hex byte Meaning
Parameter Code 06 Call type
Parameter Length 01 1 byte
Qualifier 4C ("L") Long distance call

It is unclear what determines the sequence that the MESG line is emitted by the modem. For British Telecom, modems seem to generate MESG before DATE, and for Bell Canada telcos, modems seem to generate it after NMBR/DDN_NMBR.

Additional info in this UK Telecom Google Group post.

Appendix E: SMS Relay Job sequence diagram (new in API 1.4)

Below is a sequence diagram showing how NCIDpop relays SMS to NCID Android.

The first two sequences show the use of NOT: only. The third sequence shows how RLY: was added to allow NCIDpop to "remotely" send SMS messages.

API Version Change History

As new features are added they are marked (New in API ?.?)

As features are removed, they are marked (Removed in API ?.?)

The API version number is represented by ?.?

Release Summary

API Version NCID Version Feature Sets
1.4 1.5 1 2 3 4 5
1.3 1.4 1 2 3 4
1.2 1.3 1 2 3 4
1.1 1.1 1 2 3 4
1.0 1.0 1 2 3 4

Version 1.4

General changes

  • Feature sets supported: 1 2 3 4 5
  • Released simultaneously with NCID 1.5.
  • Added definitions for line types +BLK, +CID, +END, +HUP, +MSG, +NOT, +OUT, +PID, +RLY, +WID and +CIDINFO. These represent line types from a Forwarding Gateway. They are otherwise the same as the same line types without the leading "+".

Before you begin

General notes on DATE and TIME field data
  • Added note that RLY: line types will not be checked for missing DATE and TIME fields because they are expected to be present.

Feature Set 2: Gateway Support

Forwarding Gateway (Server-to-Server) (new in API 1.4)

Feature Set 5: Relay Job Support

Appendix A: Quick Reference List of all call type line identifiers

  • Added RLY:.

Appendix B: Index to all line type definitions

  • Added RLY: and RLYLOG:.

Appendix E: SMS Relay Job sequence diagram

Version 1.3

General changes

  • Feature sets supported: 1 2 3 4
  • Released simultaneously with NCID 1.4

Feature Set 1: Modem and Device Support

Server Implementation -> Server Output Lines
  • All OPT: lines output by the server are for informational and troubleshooting purposes only. Clients can optionally make use of them by giving the user a way to display them. Otherwise, clients are not required to display them, do not need to take any action on them and can safely ignore them. See Feature Set 1 OPT: definition and Feature Set 1: Client Implementation for more information.
Client Implementation
  • All OPT: lines output by the server are for informational and troubleshooting purposes only. Clients can optionally make use of them by giving the user a way to display them. Otherwise, clients are not required to display them, do not need to take any action on them and can safely ignore them. See Feature Set 1 OPT: definition and Feature Set 1: Client Implementation for more information.

Feature Set 2: Gateway Support

Client Implementation
  • All OPT: lines output by the server are for informational and troubleshooting purposes only. Clients can optionally make use of them by giving the user a way to display them. Otherwise, clients are not required to display them, do not need to take any action on them and can safely ignore them. See Feature Set 1 OPT: definition and Feature Set 1: Client Implementation for more information.

Feature Set 3: Client Job Support

Server Implementation
  • reload the blacklist and whitelist files

    (Removed in API 1.3) if the ncidd.conf::hangup option is being used

Client Implementation
  • All OPT: lines output by the server are for informational and troubleshooting purposes only. Clients can optionally make use of them by giving the user a way to display them. Otherwise, clients are not required to display them, do not need to take any action on them and can safely ignore them. See Feature Set 1 OPT: definition and Feature Set 1: Client Implementation for more information.

Graphical client description

  • (Removed in API 1.3) only if the server sends OPT: hangup will the user have an option to force the server to reload the blacklist/whitelist files

Version 1.2

General changes

  • Feature sets supported: 1 2 3 4
  • Released simultaneously with NCID 1.3

Feature Set 1: Modem and Device Support

Server Implementation -> Server Output Lines
  • changed:
    NONAME to NO NAME
    NONUMBER to NO-NUMBER
    NOLINE to NO-LINE
Client Implementation
  • Removed OPT: ignore1 from OPT: section.

Note: In API 1.3, OPT: ignore1 was re-implemented for informational and troubleshooting purposes only.

Feature Set 2: Gateway Support

Server Implementation -> Server-to-Gateway
  • changed:
    NONAME to NO NAME
    NONUMBER to NO-NUMBER
    NOLINE to NO-LINE
    NOTYPE to -

Version 1.1

General changes

  • Feature sets supported: 1 2 3 4
  • Released simultaneously with NCID 1.1

Feature Set 1: Modem and Device Support

Server Implementation -> Optional TCI Device-to-Server

Feature Set 3: Client Job Support

Client-to-Server

Graphical client description

  • (Removed in API 1.1) only if the server sends OPT: hangup will the user be able to edit the blacklist/whitelist entries

Updated the following Client Jobs:

  • REQ: black add
  • REQ: black remove
  • REQ: white add
  • REQ: white remove

with the following:

(Removed in API 1.1) The server must have sent, and the client must have received, OPT: hangup to enable this Client Job.

Version 1.0

Documentation Change History

September 30, 2016

General changes

  • Changed fs3-job-support links to fs3-client-job support to distinguish them from the new fs5-relay-job-support links.
  • Changed all references to the MESG*<msg>* field pair to be MESG*<hexchars>*.
  • In all field pair tables, added "being sent to the server" to the description for ### and "being sent from the server" to the description for ***.

Before you begin

About configuration options for server implementations
  • Expanded list of configuration files.
  • Changed example of ncidd.conf::cidlias to be the less confusing example of ncidd.conf::lockfile.
About field pairs and line types
  • Change description and examples in Field Pairs section to explain that the prefix for a first field pair is either ### to indicate the line is being sent to the server, or *** to indicate it is being sent from the server.
General notes on NAME, NMBR, LINE and MESG field data
  • Expanded description for MESG field data.

Feature Set 1: Modem and Device Support

Modem-to-Server
  • Clarified descriptions of MESG and DDN_NMBR; changed NAME in example to be JOHN DOE.
Optional Server Hangup Extension
  • Improved description of how Hangup Extension scripts work.

Appendix D: More info about modem MESG hexadecimal characters

July 23, 2016

General changes

  • None.

Feature Set 1: Modem and Device Support

Server Implementation
Optional Server Hangup Extension

May 7, 2016

General changes

  • Updates for API 1.3.
  • API Version Change History -> Release Summary
  • Several sections in API 1.2 were incorrectly marked "(new in API 1.2)" when in fact these were documentation changes only and not functional changes. These have been corrected.
  • References to specific ncidd.conf setting names were changed to the convention <configuration file name::setting name> throughout the document.
  • Formatting changes throughout to make rendering more compatible with the Haroopad markdown editor.
  • References to hangup logic changed as appropriate to be "Internal Hangups" or "Hangup Extensions" to accommodate new Hangup Extensions.
  • When Internal Hangups are enabled, OPT: hangup lines will now have the format OPT: hangup-X where "X" is the hangup mode in the range 1-3. Log file examples were changed throughout from OPT: hangup to OPT: hangup-1.
  • When Hangup Extensions are enabled, the server will send OPT: hupmode-X lines where "X" is the hangup mode in the range 1-3.
  • Added "Released simultaneously with NCID..." to API Version history 1.0 to 1.3.
  • Added text "Appendix A:" in front of "Quick Reference List of all call type line identifiers".
  • Added text "Appendix B:" in front of "Index to all line type definitions".

Before you begin

About configuration options for server implementations

Feature Set 1: Modem and Device Support

Server Implementation
Optional Server Extensions
Optional Server Hangup Extension
Server Implementation -> Server Output Lines
  • Clarified what "hangup" means for CIDINFO: lines.
  • Expanded description for OPT: .

Feature Set 2: Gateway Support

Gateway Implementation
  • Clarified what "hangup" means for CALL: lines.

Feature Set 3: Client Job Support

Client Implementation
  • Improved wording on features that will probably be needed for a GUI client.

API Version 1.2 History

Feature Set 3: Client Job Support -> Client Implementation
  • Removed the OPT: hangup requirement from the client section but not the server section.
Feature Set 3: Client Job Support -> Client-to-Server
  • The reference to OPT: hangup added in API Version 1.1 was removed.

API Version 1.1 History

Feature Set 3: Client Job Support -> Client Job Output Lines
  • Added these lines to indicate OPT: hangup from the server was not required to edit the blacklist and whitelist files:
    > (Removed in API 1.1)
    The following require receiving OPT: hangup from the server:
  • Did not remove the OPT: hangup requirement from the server and client implementation sections.

Appendix C: Quick Reference List of all server configuration settings

December 29, 2015

General changes

  • Updates for API 1.2.
  • NCID-API converted from OpenDocument Text (.odt) to Markdown (.md).
  • Reworked formatting for all tables for better readability.
  • All ambiguous references to line or label were changed to lineid.
  • Several section headings were renamed to more clearly indicate their content.

Examples:

Old New
Modem input to the server Modem-to-Server
Server output lines for Gateway Input Server-to-Gateway
Gateway Output Lines Gateway-to-Server

Before you begin

About field pairs and line types

General notes on NAME, NMBR, LINE and MESG field data

General notes on DATE and TIME field data

Ensuring connectivity with the server

Companion documents

Feature Set 1: Modem and Device Support

Server Implementation

  • Added \n (newline) section.

Server Implementation -> Server Output Lines

  • Clarified that OPT: options are always lowercase unless otherwise indicated.

Server Implementation -> Server Alias Support

Server Implementation -> Server Hangup Support

Client Implementation -> Client-to-Server

  • Added \n (newline) section.

Optional Client-to-Module

  • Added standard input line 8 to have message type.

Feature Set 3: Client Job Support

Feature Set 3 has been significantly enhanced with new content.

Overview of Available Client Jobs

Client Implementation -> Client-to-Server

  • Added: Modifying an alias and specifying a new alias of nothing (null) is the same as removing an existing alias.
  • Added: REQ: alias remove syntax

Server Implementation

  • Fixed typo in INFO: alias section - NMBDEP was changed to NMBRDEP.

Server Implementation -> Server Output Lines

  • 400: section was clarified by adding the sentence: "Nothing is sent back to the server."
  • Added NOALIAS to INFO: section.

Client Job Examples

Appendix A: Quick Reference List of all call type line identifiers

Appendix B: Index to all line type definitions