1<!-- NCID-API.md --> 2 3<head> 4<!-- without this, some browsers will render ' ' as 'Â' --> 5<meta charset="UTF-8"> 6</head> 7 8<style> 9th { 10 white-space: nowrap; 11} 12 13table, th, td { 14 padding: 6px 13px; 15 border: 1px solid #DDD; 16 border-collapse: collapse; 17 border-spacing: 0px; 18} 19 20</style> 21 22<!-- see tail end of this file for markdown editor specific formatting/layout notes --> 23 24<!-- Haroopad won't render centered heading - outputs '#' as-is --> 25 26<center> 27# NCID API Documentation 28</center> 29 30<center> 31 32</center> 33 34<center>API 1.10</center> 35 36<center>Last edited: Jan 13, 2020</center> 37 38<center>Copyright © 2010-2020</center> 39 40<center>John L Chmielewski</center> 41<center>Todd A Andrews</center> 42 43This document contains information needed to develop servers, clients, 44client output modules and gateways for NCID (Network Caller ID). 45 46All example phone numbers and names contained herein are intended to be 47fictional. 48 49There are 5 feature sets of NCID conformance: 50 51- Feature Set 1: Modem and Device Support (required) 52 53- Feature Set 2: Gateway Support (optional) 54 55- Feature Set 3: Client Job Support (optional) 56 57- Feature Set 4: Acknowledgment Support (optional) 58 59- Feature Set 5: Relay Job Support (optional) 60 61<!-- 62[Notes to other developers who may edit this document] 63 64NOTE #1: 65Todd uses commented out [bracketed] lines to maintain his diminishing 66sanity. When doing a lot of editing, Todd uses Notepad++, sets 67Language->INI file and uses View->Fold All and View->Unfold All to 68make it easier to navigate through the different sections. For this reason, 69do not let link refs start on a line. Be careful when rewrapping! 70 71Wrong way example: 72 73Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 74[do not do this](#link-to-this-is-wrong) tempor incididunt ut labore et 75dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation 76 77Right way example, simply move another word in front of the link: 78 79Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 80eiusmod [do this](#link-to-this-is-right) tempor incididunt ut labore et 81dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation 82 83NOTE #2: 84A link ref MUST be contained entirely on one line. Do not split. Not all 85Markdown parses handle split links correctly. 86 87--> 88 89 90<!-- 91[## Table of Contents] 92--> 93 94 95## <a name="api_top"></a> Table of Contents 96 97> **[Before you begin](#b4-begin)** 98 99>> [ABOUT CONFIGURATION OPTIONS FOR SERVER IMPLEMENTATIONS](#about-config) 100 101>> [ABOUT END-OF-LINE TERMINATORS](#about-eol) 102 103>> [ABOUT LINE TYPES AND FIELD PAIRS](#about-pairs) 104 105>> [GENERAL NOTES ON NAME, NMBR, LINE AND MESG FIELD DATA](#gen-text) 106 107>> [GENERAL NOTES ON DATE AND TIME FIELD DATA](#gen-datetime) 108 109>> [ENSURING CONNECTIVITY WITH THE SERVER](#connectivity) 110 111>> [COMPANION DOCUMENTS](#companion) 112 113> **[Call/Message Line Types, Categories and Structure (new in API 1.7)](#comm)** 114 115>> [OVERVIEW](#comm-overview) 116 117>> [TABLE](#comm-table) 118 119>> [{CALLTYPES} CATEGORY STRUCTURE](#comm-calltypes) 120 121>> [{MSGTYPES} CATEGORY STRUCTURE](#comm-msgtypes) 122 123>>> [Server Output Lines](#comm-msgtypes-server) 124 125>>> [Client/Gateway Output Lines](#comm-msgtypes-client-gw) 126 127> **[Feature Set 1: Modem and Device Support](#fs1-modem-support)** 128 129>> [SERVER IMPLEMENTATION](#fs1-server-impl) 130 131>>> [Server Output Lines](#fs1-server-output) 132 133>>> [Server Alias Support](#fs1-alias-support) 134 135>>> [Server Hangup Support](#fs1-hangup-support) 136 137>>> [Modem-to-Server](#fs1-modem2server) 138 139>>> [Optional Server Extensions](#fs1-server-ext) 140 141>>> [Optional Server Hangup Extension](#fs1-hangup-ext) 142 143>>> [Optional NetCallerID Device-to-Server](#fs1-netcid2server) 144 145>>> [Optional TCI Device-to-Server (new in API 1.1)](#fs1-tci2server) 146 147>> [CLIENT IMPLEMENTATION](#fs1-client-impl) 148 149>>> [Client-to-Server](#fs1-client2server) 150 151>>> [Optional Client-to-Module](#fs1-client2module) 152 153>>> [<strike>Optional Client-to-TiVo Display</strike> <font color="dimgray">(Removed in API 1.6) </font>](#fs1-client2tivo) 154 155> **[Feature Set 2: Gateway Support](#fs2-gw-support)** 156 157>> [SERVER IMPLEMENTATION](#fs2-server-impl) 158 159>>> [XDMF Input (new in API 1.8)](#fs2-xdmf-input) 160 161>>> [Server Output Lines](#fs2-server-output) 162 163>> [GATEWAY IMPLEMENTATION](#fs2-gw-impl) 164 165>>> [Gateway-to-Server](#fs2-gw2server) 166 167>>> [Forwarding Gateway (Server-to-Server) (new in API 1.4)](#fs2-fwdgw) 168 169>> [CLIENT IMPLEMENTATION](#fs2-client-impl) 170 171>>> [Optional Client-to-Module](#fs2-client2module) 172 173> **[Feature Set 3: Client Job Support](#fs3-client-job-support)** 174 175>> [OVERVIEW OF AVAILABLE CLIENT JOBS](#fs3-overview) 176 177>> [SERVER IMPLEMENTATION](#fs3-server-impl) 178 179>>> [Server Output Lines](#fs3-server-output) 180 181>> [CLIENT IMPLEMENTATION](#fs3-client-impl) 182 183>>> [Client-to-Server](#fs3-client2server) 184 185>> [REQUIREMENTS FOR DIAL-A-NUMBER CLIENT JOB (new in API 1.6)](#fs3-dial-req) 186 187>>> [*lineid*](#fs3-dial-lineid) 188 189>>> [Server Implementation](#fs3-dial-server-impl) 190 191>>> [Client Implementation](#fs3-dial-client-impl) 192 193>> [CLIENT JOB EXAMPLES](#fs3-examples) 194 195> **[Feature Set 4: Acknowledgment Support](#fs4-ack-support)** 196 197>> [SERVER IMPLEMENTATION](#fs4-server-impl) 198 199>>> [Server Output Lines](#fs4-server-output) 200 201>> [GATEWAY IMPLEMENTATION](#fs4-gw-impl) 202 203>>> [Gateway-to-Server](#fs4-gw2server) 204 205>> [CLIENT IMPLEMENTATION](#fs4-client-impl) 206 207>>> [Client-to-Server](#fs4-client2server) 208 209> **[Feature Set 5: Relay Job Support (new in API 1.4)](#fs5-relay-job-support)** 210 211>> [RELAY JOB OVERVIEW](#fs5-overview) 212 213>> [SERVER IMPLEMENTATION](#fs5-server-impl) 214 215>> [RELAY JOB ORIGIN (RJO) IMPLEMENTATION](#fs5-origin-impl) 216 217>>> [RJO Line Type Definition](#fs5-def-rjo) 218 219>> [RELAY JOB TARGET (RJT) IMPLEMENTATION](#fs5-target-impl) 220 221>>> [RJT Line Type Definition](#fs5-def-rjt) 222 223>> [RELAY JOB EXAMPLES](#fs5-examples) 224 225> **[Sending a Text Message](#sending-messages)** 226 227> **[Country Codes](#country-codes)** 228 229> **[Emulation Programs and Test Files](#emulation)** 230 231> **[Appendix A: Copy-and-paste friendly {CALLTYPES} and {MSGTYPES}](#quick-ref-call-types)** 232 233> **[Appendix B: Index of line type definitions](#index-line-types)** 234 235> **[Appendix C: Quick Reference List of all server configuration settings](#quick-ref-serv-config)** 236 237> **[Appendix D: More info about modem MESG hexadecimal characters](#modem-mesg-hex)** 238 239> **[Appendix E: SMS Relay Job sequence diagram (new in API 1.4)](#ncidpop-sms-relay)** 240 241> **[API Version Change History](#api-history-top)** 242 243>> [Release Summary](#api-release-summary) 244 245>> [Version 1.10](#api-history-1.10) 246 247>> [Version 1.9](#api-history-1.9) 248 249>> [Version 1.8](#api-history-1.8) 250 251>> [Version 1.7](#api-history-1.7) 252 253>> [Version 1.6](#api-history-1.6) 254 255>> [Version 1.5](#api-history-1.5) 256 257>> [Version 1.4](#api-history-1.4) 258 259>> [Version 1.3](#api-history-1.3) 260 261>> [Version 1.2](#api-history-1.2) 262 263>> [Version 1.1](#api-history-1.1) 264 265>> [Version 1.0](#api-history-1.0) 266 267> **[Documentation Change History](#doc-history-top)** 268 269>> [April 24, 2019](#doc-history-2019-04-24) 270 271>> [October 25, 2018](#doc-history-2018-10-25) 272 273>> [August 17, 2018](#doc-history-2018-08-17) 274 275>> [May 31, 2018](#doc-history-2018-05-31) 276 277>> [November 5, 2017](#doc-history-2017-11-05) 278 279>> [November 6, 2016](#doc-history-2016-11-06) 280 281>> [September 30, 2016](#doc-history-2016-09-30) 282 283>> [July 23, 2016](#doc-history-2016-07-23) 284 285>> [May 7, 2016](#doc-history-2016-05-07) 286 287>> [December 29, 2015](#doc-history-2015-12-29) 288 289<!-- 290[## Before you begin] 291--> 292 293## <a name="b4-begin"></a> Before you begin 294 295 296<!-- 297[### ABOUT CONFIGURATION OPTIONS FOR SERVER IMPLEMENTATIONS] 298--> 299 300> ### <a name="about-config"></a> ABOUT CONFIGURATION OPTIONS FOR SERVER IMPLEMENTATIONS 301 302>> This API document attempts to describe server interactions with 303gateways, clients, extensions, etc. without regard to a specific operating 304system or specific programming methods and conventions. However, for the 305purpose of reading this document we will reference configuration options 306using the following convention: 307 308>>**<configuration file name::setting name>** 309 310>> In the case of the official NCID distribution for Unix/Linux platforms, 311there are several configuration files. Here are just a few of them: 312 313>>> 314Purpose | Unix/Linux File Name | Convention used in this API 315--------------------------|----------------------|:--------------------------- 316Server settings | ncidd.conf | **<ncidd.conf::setting name>** 317Alias mappings | ncidd.alias | **<ncidd.alias::alias definition>** 318Blacklist | ncidd.blacklist | **<ncidd.blacklist::call name or number>** 319Whitelist | ncidd.whitelist | **<ncidd.whitelist::call name or number>** 320Universal Client settings | ncid.conf | **<ncid.conf::setting name>** 321SIP Gateway settings | sip2ncid.conf | **<sip2ncid.conf::setting name>** 322YAC Gateway settings | yac2ncid.conf | **<yac2ncid.conf::setting name>** 323XDMF Gateway settings | xdmf2ncid.conf | **<xdmf2ncid.conf::setting name>** 324 325>> An example of a setting name in the server configuration file would be 326`lockfile`. Within this document you would see the setting referenced 327as **ncidd.conf::lockfile**. 328 329>> If a developer wishes to create his or her own NCID server, any 330configuration file name and setting name convention desired can be used. 331For example, an NCID server for Windows might use a file name called 332**ncid-server.ini** and a setting called **LockFile=**. 333 334>> Using the **<configuration file name::setting name>** convention 335allows a developer to correlate the setting names referenced in this API 336with the developer's own conventions. In this regard, you can think of 337**<configuration file name::setting name>** as a reference to a 338concept or definition. **ncidd.conf::lockfile** therefore refers to the 339path of the server's serial port lock file. An alphabetized summary of 340all server options, including a brief description, can be found 341in [Appendix C: Quick Reference List of all server configuration settings](#quick-ref-serv-config). 342 343<!-- 344[### ABOUT END-OF-LINE TERMINATORS] 345--> 346 347> ### <a name="about-eol"></a> ABOUT END-OF-LINE TERMINATORS 348> 349>> Carriage return characters may appear in this document as <CR>, 350x0D, or \r. Line feeds a.k.a. new lines may appear as <LF>, 351<NL>, x0A, or \n. 352 353>> Because of NCID's Unix origin, generally speaking, line feeds are the 354preferred line terminator. This applies not only to client/server 355communications but also to reading files (e.g., **ncidd.conf**, 356**ncidd.alias**, **ncid.conf**, **ncid-mysql.conf**, etc.) as well as 357writing files (e.g., **ncidd.log**, **ncidd.alias**, **cidcall.log**, 358etc.). 359 360>> Even though line feeds are preferred, the Unix distributions of NCID 361will generally play it safe and look for both <CR> and <LF>, 362stripping these characters prior to storing data in memory or otherwise 363processing the read/received data. In other words, NCID does not enforce 364which end-of-line terminator is used when reading files or receiving data, 365it just requires a minimum of one (<CR> or <LF>) to be used. 366 367>> The exception is when NCID must *write* or *send* data to third party 368hardware, processes, or protocols. In these cases, third party 369requirements will dictate the end-of-line terminators to be used. NCID 370already takes this exception into account for all officially supported 371third party interactions. 372 373<!-- 374[### ABOUT LINE TYPES AND FIELD PAIRS] 375--> 376 377> ### <a name="about-pairs"></a> ABOUT LINE TYPES AND FIELD PAIRS 378 379>> The reason for the following restrictions is to allow future NCID 380 programs and scripts to be as backward compatible as possible. This is 381 particularly important in the case of third party software that may 382 not be updated at the same time as a new NCID release. 383 384>> ### Line Types 385 386>> - This document uses <font color="red">XXX</font>, <font color="red">XXX:</font>, 387 <font color="red">XXXLOG:</font>, etc. where <font color="red">XXX</font> 388 is a place holder when discussing something that applies to multiple 389 line types. 390 391>> - It is very important for a program or script to ignore line types 392 (e.g., <font color="red">200</font>, <font color="red">210</font>, 393 <font color="red">CID:</font>, <font color="red">HUP:</font>, 394 <font color="red">REQ:</font> etc.) that it does not recognize. It 395 should not trigger a fatal error. 396 397>> ### Field Pairs 398 399>> A field pair is defined as <field label><field data>, 400 with zero or more delimiter characters between them. 401 402>> The very first field pair for a line **might** begin with the three 403 characters \#\#\# to indicate the data is being sent TO the server, or 404 begin with the three characters \*\*\* to indicate the data is being 405 received FROM the server. 406 407>> **It is very important NOT to assume that the <u>order</u> of field 408 pairs will always be the same across NCID versions.** 409 410>> For example, if today a hypothetical layout of field pairs looks like this: 411 412>>> `XYZ: ***DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*` 413 414>> There is no guarantee that the order won't be changed. Perhaps a 415 future version would swap MESG and NAME: 416 417>>> `XYZ: ***DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*NAME*<name>*MESG*<hexchars>*` 418 419>> Another example showing ###/.../+++ field delimiters for the field 420 pairs: 421 422>>> `ABCD: ###DATE<datetime>...CALL<type>...LINE<lineid>...NMBR<number>... 423 NAME<name>+++` 424 425>> might someday get changed to put NMBR and NAME first: 426 427>>> `ABCD: ###NMBR<number>...NAME<name>...DATE<datetime>...CALL<type>... 428 LINE<lineid>+++` 429 430>> Any programs or scripts you develop on your own must be flexible in 431 parsing out <field label><field data>, wherever they 432 might be located in a line. 433 434>> **It is very important for a program or script to ignore 435 <field label><field data> pairs that it does not 436 recognize. ** 437 438>> For example, if at some point in the future a new field 439 pair with the hypothetical label of JJJJ was added, your programs 440 or scripts should not trigger a fatal error. And it might be 441 added at any location in the line, not just at the end: 442 443>>> `XYZ: ***DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*JJJJ*<data>*MESG*<hexchars>*NAME*<name>*` 444 445>>> `ABCD: ###DATE<datetime>...CALL<type>...LINE<lineid>...NMBR<number>... 446 JJJJ<data>...NAME<name>+++` 447 448<!-- 449[### GENERAL NOTES ON NAME, NMBR, LINE AND MESG FIELD DATA] 450--> 451 452> ### <a name="gen-text"></a> GENERAL NOTES ON NAME, NMBR, LINE AND MESG FIELD DATA 453 454>> ### NAME 455 456>> - a string of characters that indicates the Caller ID name from a 457 modem, gateway or smartphone, or a name alias 458 459>> - can include embedded spaces (do not surround with quotes) 460 461>> - can include punctuation marks 462 463>> - can be one of the special names OUT-OF-AREA, ANONYMOUS and PRIVATE 464 465>> - if there is no name, it should not be left blank (although this is 466 not strictly enforced and you may get unpredictable results), but 467 instead should contain NO NAME or a dash ("-") 468 469>> - name should not exceed 50 characters and in particular the NCID 470 server enforces an alias maximum length of 50. On smartphones the NAME 471 becomes the SMS text and be aware that some smartphones send messages 472 several hundred bytes in length. 473 474>> ### NMBR 475 476>> - a string of characters that indicates the Caller ID number from a 477 modem, gateway or smartphone, or a number alias 478 479>> - usually does not have embedded spaces 480 481>> - if punctuation marks are present, it is usually a dash ("-") 482 483>> - can be one of the special names OUT-OF-AREA, ANONYMOUS and PRIVATE 484 485>> - if there is no number, it should not be left blank (although this is 486 not strictly enforced and you may get unpredictable results), but 487 instead should contain NO-NUMBER or a dash ("-"). The general size limit 488 in the telephone industry is 15 characters or less. 489 490 491>> ### LINE 492 493>> - referred to as <lineid> in this API, it is a string of characters 494 that identifies the origin telephone line of a call from a modem, 495 smartphone or gateway, or a device identifier for a message 496 497>> - usually does not have embedded spaces 498 499>> - usually does not have punctuation marks 500 501>> - usually no more than six characters 502 503>> - you can apply aliases to LINE data 504 505>> - if there is no lineid, it should not be left blank (although this is 506 not strictly enforced and you may get unpredictable results), but 507 instead should contain NO-LINE or a dash ("-"). 508 509>> ### MESG 510 511>> - if present, a string of hexadecimal characters that represent raw 512>> caller ID data bytes that the modem does not understand 513>> (see [Appendix D: More info about modem MESG hexadecimal characters](#modem-mesg-hex)) 514>> 515>> - this is a rarely populated field and should not be confused with the 516>> <font color="red">MSG:</font> and <font color="red">NOT:</font> call 517>> line types 518 519>> - NCID does not currently interpret the MESG code in any way but 520>> simply captures it and sends it on to listening clients 521 522>> - no defined length limit 523 524>> - if there are no hexadecimal characters, it should not be left blank 525>> when populating the field pair (although this is not strictly enforced 526>> and you may get unpredictable results), but instead should contain NONE 527>> or a dash ("-") 528 529 530>> ### The Dash 531 532>> - When a call or message has an unknown NAME, NMBR, LINE or MESG the 533 field may contain the text NO NAME, NO-NUMBER, NO-LINE or NONE 534 respectively. Clients should also allow for any of these fields to be a 535 single dash to suppress the text from being displayed, that is, if the 536 field data contains a dash don't show anything. 537 538<!-- 539[### GENERAL NOTES ON DATE AND TIME FIELD DATA] 540--> 541 542> ### <a name="gen-datetime"></a> GENERAL NOTES ON DATE AND TIME FIELD DATA 543 544>> ### DATE 545 546>> The general rule of thumb is that dates related to call data will 547 already be passed from the telco to NCID in the correct format for 548 the country where NCID is running -- month/day or day/month -- as 549 provided by the modem or other device. They will in turn be stored 550 in the call log in the same format. 551 552>> There are two exceptions: 553 554>> - If NCID does not detect a DATE field pair it will create one from 555 the current date. Be aware that such dates will always be in the 556 format month/day regardless of the country where NCID is running. 557 558>>> (New in API 1.4) The field pair contents of <font color="red">RLY:</font> 559 line types are NOT checked at all and are expected to include the 560 DATE field pair. 561 562>> - The call accounting <font color="red">END:</font> line type has 563 three date-like field pairs: 564 565>>> - DATE, which will come from the modem or device and falls under 566 the general rule of thumb above 567 568>>> - SCALL and ECALL, which represent the start and end of a call 569 for call accounting, will always be in the format month/day. 570 571>> ### <datetime> 572 573>> - This is a date and time "combo" field where the date is only four 574 digits (mmdd or ddmm) and the time is the normal four (hhmm) as 575 described in the next section, TIME. The four digit date follows the 576 general rule of thumb above. 577 578>> ### TIME 579 580>> - All TIME fields are expected to be in military style 24-hour format 581 (hours 0-23). Clients have the option of converting to 12-hour AM/PM 582 format. 583 584>> - If NCID does not detect a TIME field pair it will create one from 585 the current time. 586 587>>> (New in API 1.4) The field pair contents of <font color="red">RLY:</font> 588 line types are NOT checked at all and are expected to include the 589 TIME field pair. 590 591>> - NCID does not care or know anything about time zones. 592 593<!-- 594[### ENSURING CONNECTIVITY WITH THE SERVER] 595--> 596 597> ### <a name="connectivity"></a> ENSURING CONNECTIVITY WITH THE SERVER 598 599<!-- 600 601John Gruber's 'markdown' Perl script doesn't seem to consistently convert 602lines like the following to html: 603 604 >> - ##### <font color="red">\\n (newline)</font> 605 606gets rendered with the ##### as-is instead of being convert to h5 tags: 607 608 >> - ##### <font color="red">\\n (newline)</font> 609 610so use the equivalent <h5> tags: 611 612 >> - <h5><font color="red">\\n (newline)</font></h5> 613 614Or, just use 'pandoc' instead of 'markdown': 615 616 pandoc -o NCID-API.html NCID-API.md 617 618--> 619 620>> There are three different methods that clients and gateways can use 621 to test their connection to the server. 622 623>> - ##### <font color="red">\\n (newline)</font> 624 625>>> Supported in Feature Set 1. This is the most basic method. A client 626 or gateway simply sends a <font color="red">\\n (newline)</font> to 627 the server and checks for errors. The server will make a note in its 628 log that it received a blank line, but otherwise ignores it. The 629 server does not send any response. 630 631>> - ##### <font color="red">REQ: YO</font> 632 633>>> Supported in Feature Set 4. A client or gateway can send 634 <font color="red">REQ: YO</font> and expect an 635 <font color="red">ACK: REQ YO</font> response from the server. 636 637>> - ##### <font color="red">REQ: ACK</font> 638 639>>> Supported in Feature Set 4. A client or gateway can send 640 <font color="red">REQ: ACK <commands and arguments> </font> and 641 expect an <font color="red">ACK: REQ ACK <commands and 642 arguments></font> response from the server. 643 <font color="red">ACK: REQ ACK</font> sets an "ack" flag for the 644 client that tells the server to acknowledge gateway 645 <font color="red">CALL:</font>, <font color="red">CALLINFO:</font> 646 and <font color="red">NOT:</font> lines. In other words, the server 647 is expected to echo back all commands and arguments it receives. 648 649<!-- 650### COMPANION DOCUMENTS 651--> 652 653> ### <a name="companion"></a> COMPANION DOCUMENTS 654 655>> You may wish to have the following documents handy as you work with 656 the API: 657 658>> ### User Manual: 659 660>>> - ["Using NCID" chapter -> "Using Aliases" section](http://ncid.sourceforge.net/doc/NCID-UserManual.html#alias_top) 661 662>>> - ["Using NCID" chapter -> "Using Hangup" section](http://ncid.sourceforge.net/doc/NCID-UserManual.html#hangup_top) 663 664<!-- 665[## Call/Message Line Types, Categories and Structure (new in API 1.7)] 666--> 667 668## <a name="comm"></a> Call/Message Line Types, Categories and Structure (new in API 1.7) 669 670<!-- 671[### OVERVIEW] 672--> 673 674> ### <a name="comm-overview"></a> OVERVIEW 675 676>> New NCID releases are often accompanied by new line types for call- 677and/or message-type data. The actual structure of the data is usually 678identical with already defined line types and they differ only by the 679<font color="red">XXX:</font color> code at the beginning of each line. 680 681>> In order to remove a significant amount of redundant info in this API, 682we've introduced the concept of *category types*. As new line types are 683added that have the same structure, they'll be assigned to a category. 684 685>> The categories have a secondary benefit in that they will make it 686easier to insure backward compatibility with output modules. Prior to 687API 1.7 it was necessary for end users to carefully examine their 688customized output module configuration files when upgrading to a new 689NCID release. If a new line type was added, it usually meant that the 690configuration file would need to be manually edited in order to make use 691of the new line type. Now, whenever possible and practical, line type 692categories can be used in the configuration files and new NCID releases 693will automatically include the new line types, all without requiring 694customized configuration files to be manually edited. 695 696>> Configuration files can still explicitly use line types if desired or 697if the use of categories is not practical. 698 699>> Over time, we'll be updating all documentation to use the categories. 700This will result in less maintenance work for us. 701 702<!-- 703[### TABLE] 704--> 705 706> ### <a name="comm-table"></a> TABLE 707 708>> The **FS** and **API** columns, respectively, indicate the minimum 709Feature Set and API version required. 710 711>> Click on a link to be taken to its definition. 712 713>> 714 \#|Type |Category | Description |FS|API 715--:|----------------------------------------------:|---------|:--------------------------|--|--- 716 1|[<font color="red">BLK:</font>](#line-type-blk)|CALLTYPES|Blacklisted Call Blocked |2 |1.0 717 2|[<font color="red">CID:</font>](#line-type-cid)|CALLTYPES|Incoming Call |1 |1.0 718 719<br> 720 721>> 722 \#|Type |Category | Description |FS|API 723--:|----------------------------------------------:|---------|:--------------------------|--|--- 724 3|[<font color="red">HUP:</font>](#line-type-hup)|CALLTYPES|Blacklisted Call Hangup |1 |1.0 725 4|[<font color="red">MWI:</font>](#line-type-mwi)|CALLTYPES|Voicemail Message Waiting |2 |1.7 726 5|[<font color="red">OUT:</font>](#line-type-out)|CALLTYPES|Outgoing Call |2 |1.0 727 6|[<font color="red">PID:</font>](#line-type-pid)|CALLTYPES|Incoming Smartphone Call|2 |1.0 728 7|[<font color="red">PUT:</font>](#line-type-put)|CALLTYPES|Outgoing Smartphone Call |2 |1.7 729 8|[<font color="red">RID:</font>](#line-type-rid)|CALLTYPES|Ringback Call |2 |1.7 730 9|[<font color="red">WID:</font>](#line-type-wid)|CALLTYPES|Call Waiting Caller ID |2 |1.1 731 10|<font color="red">MSG:</font> |MSGTYPES |Message <br>[(client output)](#line-type-msg-client) or <br>[(server alert)](#line-type-msg-server-alerts) or [(gateway alert)](#line-type-msg-gw-alerts) or <br>[(server output)](#line-type-msg-server-output) or [(gateway output)](#line-type-msg-gw-output)|1 |1.0 732 11|<font color="red">NOT:</font> |MSGTYPES |Notice of a Smartphone message <br>[(server output)](#line-type-not-server) or [(gateway output)](#line-type-not-gateway) |2 |1.0 733 734<!-- 735[### {CALLTYPES} CATEGORY STRUCTURE] 736--> 737 738> ### <a name="comm-calltypes"></a> {CALLTYPES} CATEGORY STRUCTURE 739 740>> The text line is comprised of field pairs, the first contains the 741>> field label and the second contains the field data. Fields are 742>> separated by a \* and the first field starts after a single \*. 743>> The category does not appear in the data. 744 745>>>> `XXX: *DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*MESG*<hexchars>*NAME*<name>*` 746 747>>> The line is comprised of the following field pairs: 748 749>>>> 750 <label>\*<data>\* | Description 751 ------------------|:-------------------------------------------------------- 752 DATE\*date\* | where date is [mmddyyyy or ddmmyyyy](#gen-datetime), m = month, d = day, y = year 753 TIME\*time\* | where time is [hhmm in 24-hour format](#gen-datetime), h = hour, m = minute 754 LINE\*lineid\* | where lineid is a [string of characters](#gen-text), NO-LINE or - 755 756<br> 757<br> 758 759>>>> 760 <label>\*<data>\* | Description 761 ------------------|:-------------------------------------------------------- 762 NMBR\*number\* | where number is a [string of characters](#gen-text), NO-NUMBER or - 763 MESG\*hexchars\* | where hexchars is a [string of characters](#gen-text) or NONE 764 NAME\*name\* | where name is a [string of characters](#gen-text), a name from the smartphone address book (use "UNKNOWN" if not in the address book), NO NAME or - 765 766 767 768<!-- 769[### {MSGTYPES} CATEGORY STRUCTURE] 770--> 771 772> ### <a name="comm-msgtypes"></a> {MSGTYPES} CATEGORY STRUCTURE 773 774>> <font color="red">{MSGTYPES}</font> allow for free-form text following 775the line type. 776 777>> Alerts have no field pairs. The Server and Client/Gateway lines do have 778field pairs and the difference is that the first field after the free-form 779text begins with \*\*\* (sent from server) or \#\#\# (sent to server) 780respectively. 781 782>> 783 784<!-- 785[### {MSGTYPES} Category Structure for Alerts] 786--> 787 788>> ### <a name="comm-msgtypes-alerts"></a> Server/Gateway Alerts 789 790>>>> `MSG: <message>` 791 792>>> Alerts have a <font color="red">MSG:</font> line type followed by 793free-form text; they have no field pairs. 794 795<!-- 796[### {MSGTYPES} Category Structure for Server Output Lines] 797--> 798 799>> ### <a name="comm-msgtypes-server"></a> Server Output Lines 800 801>>>> `XXX: <message>***DATE*<date>*TIME*<time>*NAME*<name>*NMBR*<number>*LINE*<lineid>*MTYPE*<io>*` 802 803>>> The line is comprised of the following field pairs: 804 805>>>> 806 <label>\*<data>\* | Description 807 ------------------|:-------------------------------------------------------- 808 \*\*\* | start of the information part of the message being sent from the server 809 DATE\*date\* | where date is [mmddyyyy or ddmmyyyy](#gen-datetime), m = month, d = day, y = year 810 TIME\*time\* | where time is [hhmm in 24-hour format](#gen-datetime), h = hour, m = minute 811 NAME\*name\* | where name is a [string of characters](#gen-text), NO NAME or - 812 813<br> 814 815>>>> 816 <label>\*<data>\* | Description 817 ------------------|:-------------------------------------------------------- 818 NMBR\*number\* | where number is a [string of characters](#gen-text), NO-NUMBER or - 819 LINE\*lineid\* | where lineid is a [string of characters](#gen-text), NO-LINE or - 820 MTYPE\*io\* | where io is either IN, OUT or - 821 822<!-- 823[### {MSGTYPES} Category Structure for Client/Gateway Output Lines] 824--> 825 826>> ### <a name="comm-msgtypes-client-gw"></a> Client/Gateway Output Lines 827 828>>>> `XXX: <message>###DATE*<date>*TIME*<time>*NAME*<name>*NMBR*<number>*LINE*<lineid>*MTYPE*<io>*` 829 830>>> The line is comprised of the following field pairs: 831 832>>>> 833 <label>\*<data>\* | Description 834 ------------------|:-------------------------------------------------------- 835 \#\#\# | start of the information part of the message being sent to the server 836 DATE\*date\* | where date is [mmddyyyy or ddmmyyyy](#gen-datetime), m = month, d = day, y = year 837 TIME\*time\* | where time is [hhmm in 24-hour format](#gen-datetime), h = hour, m = minute 838 NAME\*name\* | where name is a [string of characters](#gen-text), NO NAME or - 839 NMBR\*number\* | where number is a [string of characters](#gen-text), NO-NUMBER or - 840 LINE\*lineid\* | where lineid is a [string of characters](#gen-text), NO-LINE or - 841 MTYPE\*io\* | where io is either IN, OUT or - 842 843<!-- 844[## Feature Set 1: Modem and Device Support] 845--> 846 847## <a name="fs1-modem-support"></a> Feature Set 1: Modem and Device Support 848 849<!-- 850[### FS1: SERVER IMPLEMENTATION] 851--> 852 853> ### <a name="fs1-server-impl"></a> SERVER IMPLEMENTATION 854 855>> If you want to implement a server to communicate with NCID clients 856and gateways: 857 858>> - listen to port 3333 for a connection or whatever port is specified 859 by **ncidd.conf::port** 860 861>> - send a <font color="red">200</font> text message to identify the 862 server and version 863 864>> - send a <font color="red">210</font> text message to identify the 865 API version and supported feature sets 866 867>> - (New in API 1.5) immediately after sending a <font color="red">210</font> line, 868 receive and process zero or more <font color="red">HELLO:</font> lines 869 870>> - <a name="fs1-modem-support-send-log"></a>check server 871 **ncidd.conf::send cidlog** to determine whether to send the call log 872 873>>> - if not configured to send it, or the size exceeds 874 **ncidd.conf::cidlogmax**, send a 875 <font color="red">251 Call log not sent</font> message 876 877>>> - if configured to send it but it is empty, send a 878 <font color="red">252 Call log empty</font> message 879 880>>> - if configured to send it but the file does not exist, send a 881 <font color="red">253 No call log</font> message 882 883>>> - (New in API 1.10) if configured to send it and it is not empty, send a 884 <font color="red">254 Start of call log</font> message 885 886>>> - if configured to send it and it is not empty, send the call log 887 and end with a <font color="red"> 250 End of call log</font> 888 message 889 890>> - optionally, send a list of server-supported Client Job options to 891 client, one <font color="red">OPT: <option></font> line for 892 each option 893 894>> - if a server setting is being temporarily overridden by a 895 <font color="red">HELLO: CMD: <command></font> line, 896 clear the override so it will not apply to future connections 897 898>> - send a <font color="red">300 End of server startup</font> message 899 900>> - putting all of the above together, a typical client connection 901 start-up looks like this: 902>> 903>>> 200 Server: ncidd (NCID) x.x 904>>> 210 API x.x Feature Set x x x x ... 905>>> Client Sent: HELLO: IDENT: client ncid (NCID) x.x 906>>> Client Ident: client ncid (NCID) x.x 907>>> CIDLOG: \*DATE\*12012015\*TIME\*0028\*LINE\*POTS\*NMBR\*... 908>>> HUPLOG: \*DATE\*12012015\*TIME\*0105\*LINE\*POTS\*NMBR\*... 909>>> ... 910>>> 254 Start of call log 911>>> 250 End of call log 912>>> OPT: hangup-1 913>>> OPT: ... 914>>> 300 End of connection startup 915 916 917>> - when a call is received: 918 919>>> - if configured by **ncidd.conf::send cidinfo** to send ring info, 920 send a <font color="red">CIDINFO:</font> line at each ring with a 921 LINE indicator (default '-') and the ring count 922 923>>> - generate an alias for the name, number and/or line if it is in the 924 alias file 925 926>>> - if optional Internal Hangup support (**ncidd.conf::hangup**) is 927 implemented: 928 929>>>> - hangup a call if it is in the **ncidd.alias** file 930 but not in the **ncidd.whitelist** file 931 932>>>> - hangup a call using a modem: 933 934>>>>> - modem off-hook 935>>>>> - send <font color="red">HUP:</font> line to connected clients 936>>>>> - delay 937>>>>> - modem on-hook 938 939>>> - if optional Hangup Extensions support (**ncidd.conf::hupmode**) is 940 implemented: 941 942>>>> - hangup a call if the Hangup Extension script determines it should 943 be terminated 944 945>>>> - hangup a call using a modem: 946 947>>>>> - modem off-hook 948>>>>> - send <font color="red">HUP:</font> line to connected clients 949>>>>> - delay 950>>>>> - modem on-hook 951 952>>> - otherwise, if the call is not being terminated, send a 953 <font color="red">CID:</font> line to connected clients when a call 954 is received 955 956>>> - send a <font color="red">CIDINFO:</font> line after ringing stops, 957 with a ring count of 0 958 959>>> - send a <font color="red">CIDINFO:</font> when automatic hangup is completed, 960 with a ring count of -4. 961 962>> - send a <font color="red">MSG:</font> line to connected clients with 963 an important server warning or a user message 964 965>> - maintain a constant TCP connection with the clients 966 967>> - allow clients to send a <font color="red">\\n (newline)</font> to 968 determine if the server is still available but ignore it (no 969 response is sent back to the client) 970 971>> - detect clients as they come and go 972 973>>> - (New in API 1.6) allow clients to send an optional 974 <font color="red">GOODBYE</font> (note that there is no trailing 975 colon) line to close the connection to the server 976 977<!-- 978[### FS1: Server Output Lines] 979--> 980 981>> 982>> ### <a name="fs1-server-output"></a>Server Output Lines 983 984>> When the server sends information to a client or gateway, it sends the 985 data as lines of text that start with a line label. This defines line 986 types. The current line labels are: 987 988>> - <a name="line-type-200"></a><font color="red">200</font> 989 990>>> The server version message. The wording stays the same, but the 991 version number changes each time the server is updated. 992 993>>> For example, if the server was version 1.0: 994 995>>>> `200 Server: ncidd (NCID) 1.0` 996 997>> - <a name="line-type-210"></a><font color="red">210</font> 998 999>>> The server API version and feature sets. This is to inform clients 1000 and gateways what features are implemented. All supported feature 1001 sets must be included. 1002 1003>>> For example, if the API version is 1.0 then four feature sets are 1004 supported: 1005 1006>>>> `210 API 1.0 Feature Set 1 2 3 4` 1007 1008>> - <a name="line-type-25x"></a><font color="red">250</font> - <font color="red">254</font> 1009 1010>>> A call log message sent at server startup: 1011 1012>>>> `250 End of call log` 1013 1014>>>> `251 Call log not sent` 1015 1016>>>> `252 Call log empty` 1017 1018>>>> `253 No Call log` 1019 1020>>>> `254 Start of call log` 1021 1022>> - <a name="line-type-300"></a><font color="red">300</font> 1023 1024>>> End of the connection startup message: 1025 1026>>>> `300 End of connection startup` 1027 1028>> - <a name="line-type-cid"></a><font color="red">CID:</font> 1029 1030>>> An incoming Caller ID text line. It is sent to the clients and saved 1031 in the call log when a call is received. 1032 1033>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes). 1034 1035>> - <a name="line-type-cidinfo"></a><font color="red">CIDINFO:</font> 1036 1037>>> A text line that indicates the telephone LINE identifier and ring 1038information. The text line is comprised of field pairs, the first 1039contains the field label and the second contains the field data. Fields 1040are separated by a \* and the first field starts after a \*. The ring 1041information is only obtained from modems that indicate each ring or 1042gateways that use ring to indicate the type of call termination. Note 1043that "termination" for <font color="red">CIDINFO:</font> lines does not 1044refer to *automatic* Internal Hangups or Hangup Extensions. Instead, it 1045refers to a person on the phone who triggers the hangup manually, or the 1046telco that ends a call that has not been answered after a certain number 1047of rings. 1048 1049>>>> `CIDINFO: *LINE*<lineid>*RING*<count>*TIME*<time>*` 1050 1051>>> The <font color="red">CIDINFO:</font> line has the following fields: 1052 1053>>>> 1054 <label>\*<data>\* | Description 1055 ------------------|:-------------------------------------------------------- 1056 LINE\*lineid\* | where lineid is a [string of characters](#gen-text), NO-LINE or - 1057 RING\*count\* | where count is 0, -1, -2, -3, -4 or a positive value<br>incremented at each ring<br> 0 = (modem) ringing has stopped<br>-1 = (gateway) call terminated without pickup<br>-2 = (gateway) call terminated after pickup<br>-3 = (gateway) BUSY signal for incomplete call<br>-4 = (modem) automatic hangup completed 1058 TIME\*time\* | where time is [hh:mm:ss in 24-hour format](#gen-datetime),<br>h = hour, m = minute, s=second 1059 1060>>> Ring indication example sent to the clients for ring count 4 and line 1: 1061 1062>>>> `CIDINFO: *LINE*1*RING*4*TIME*16:20:05*` 1063 1064>>> Example of a POTS line label and the end of ringing indicator: 1065 1066>>>> `CIDINFO: *LINE*POTS*RING*0*TIME*16:20:05*` 1067 1068>>> A SIP gateway example indicating termination without pickup and a 1069VOIP line label: 1070 1071>>>> `CIDINFO: *LINE*VOIP*RING*-1*TIME*16:20:05*` 1072 1073>>> A SIP gateway example indicating termination after pickup and a 1074VOIP line label: 1075 1076>>>> `CIDINFO: *LINE*VOIP*RING*-2*TIME*16:20:05*` 1077 1078>> - <a name="line-type-hup"></a><font color="red">HUP:</font> 1079 1080>>> If Internal Hangup support (**ncidd.conf::hangup**) or Hangup 1081Extensions support (**ncidd.conf::hupmode**) is implemented, then when a 1082call is automatically terminated, a <font color="red">HUP:</font> (Hung 1083Up Phone) line is created by replacing the <font color="red">CID:</font> 1084label with the <font color="red">HUP:</font> label. 1085 1086>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes). 1087 1088>> - <a name="line-type-log"></a><font color="red">LOG:</font> 1089 1090>>> When the server sends the call log, it adds the <font 1091 color="red">LOG:</font> tag to every line that does not contain a 1092 recognized line label. The following is an example of a comment line 1093 that may be in the file: 1094 1095>>>> `LOG: # Aug 1 00:30:01 localhost newsyslog[35020]: logfile turned over` 1096>> 1097 1098>> - <a name="line-type-msg-server-alerts"></a><font color="red">MSG:</font> (server alerts) 1099 1100>>> A text line containing a server alert that is sent to the 1101 clients and saved in the call log. It has free-form text only and no 1102 field pairs. 1103 1104>>> It has the [{MSGTYPES} Category Structure for Server/Gateway Alerts](#comm-msgtypes-alerts). 1105 1106>>> Example: 1107 1108>>>> 1109 MSG: Caller ID Logfile too big: (95000 > 90000) bytes 1110 1111>> - <a name="line-type-msg-server-output"></a><font color="red">MSG:</font> (server output) 1112 1113>>> A text line containing a server message that is sent to the 1114 clients and saved in the call log. 1115 1116>>> It has the [{MSGTYPES} Category Structure for Server Output Lines](#comm-msgtypes-server). 1117 1118>> - <a name="line-type-opt"></a><font color="red">OPT: <hangup-X|hupmode-X|ignore1|regex-X></font> <br> 1119 <font color="red">OPT: LineIDS: <lineid> [<lineid>] 1120 ....</font> (new in API 1.6) 1121 1122>>> A server option sent to all the clients. Multiple 1123 <font color="red">OPT:</font> lines are permitted and the lines do not 1124 need to be sent in any particular order. Unless otherwise indicated, options 1125 are always in lowercase. 1126 1127>>>- <font color="red">OPT: hangup-X</font> 1128 1129>>>> Informational only, corresponds to the value of **ncidd.conf::hangup** 1130 where "X" is in the range 1-3. This line is not sent if **ncidd.conf::hangup** 1131 has the value zero. 1132 1133>>>- <font color="red">OPT: hupmode-X</font> 1134 1135>>>> Informational only, corresponds to the value of **ncidd.conf::hupmode** 1136 where "X" is in the range 1-3. This line is not sent if **ncidd.conf::hupmode** 1137 has the value zero. 1138 1139>>>- <font color="red">OPT: ignore1</font> 1140 1141>>>> Informational only, corresponds to the value of **ncidd.conf::ignore1**. 1142 This line is not sent if **ncidd.conf::ignore1** has the value zero. 1143 1144>>>- <font color="red">OPT: regex-X</font> 1145 1146>>>> Informational only, corresponds to the value of **ncidd.conf::regex** 1147 where "X" is in the range 1-2. This line is not sent if **ncidd.conf::regex** 1148 has the value zero. 1149 1150>>>- <font color="red">OPT: LineIDS: <lineid> <lineid> ....</font> (new in API 1.6) 1151 1152>>>> When **ncidd.conf::cidinput** indicates that an "AT" modem is connected, 1153 <font color="red">OPT: LineIDS:</font> becomes a list of each 1154 **ncidd.conf::lineid**, up to a maximum 1155 of four, after applying LINE alias(es). This is a space-delimited 1156 list and if any **ncidd.conf::lineid** contains embedded spaces, 1157 enclose it in quotes. 1158 1159>>>> Example: 1160 1161>>>>> `OPT: LineIDS: POTS "WORK 1" VOIP "WORK 2"` 1162 1163>>>> <font color="red">OPT: LineIDS:</font> is not sent if 1164 **ncidd.conf::cidinput** indicates no "AT" modem is attached. 1165 1166>>>> When there is more than one lineid, clients must allow the user to 1167 select from this list when implementing Feature Set 3 1168 <font color="red">REQ: DIAL</font>. 1169 1170>>>> Multiple modem support is currently incomplete; 1171 <font color="red">OPT: LineIDS:</font> will contain only one lineid. 1172 1173>>> (New in API 1.3) Unless otherwise noted, all <font color="red">OPT:</font> 1174lines output by the server are for informational and troubleshooting 1175purposes only. Clients can optionally make use of them by giving the user 1176a way to display them. Otherwise, clients are not required to display 1177them, do not need to take any action on them and can safely ignore them. 1178See [Feature Set 1: Client Implementation](#fs1-client-impl) for 1179more information. 1180 1181<!-- 1182[### FS1: Server Alias Support] 1183--> 1184 1185>> ### <a name="fs1-alias-support"></a> Server Alias Support 1186>> 1187 1188>> The name, number and telephone line of a call are checked for an 1189 alias. If a match is found it will be replaced by its alias 1190 before the call is added to the call log and before the call 1191 information is sent to the clients. 1192 1193>> NCID's support for aliases is extensive and there is an entire 1194 section in the User Manual devoted to the subject (see the chapter 1195 "Using NCID"). Continue reading below for: 1196 1197>> - only API-specific topics 1198 1199>> - a summary of all alias types 1200 1201>> - a summary of alias-related configuration options in **ncidd.conf** 1202 1203>> Alias support is required in Feature Set 1. 1204 1205>> Clients implementing Feature Set 3: Client Job Support, can also 1206 be used to maintain aliases. Such clients will also provide a way 1207 to force the server to reload its alias table. 1208 1209>>> ##### Alias Types 1210 1211>>> There are six types of aliases. The text in the Code column below 1212 is used internally by NCID to distinguish the types and you'll see it 1213 used throughout this document. 1214 1215>>> 1216 Type | Code 1217 :--------------|---------- 1218 number | NMBRONLY 1219 name | NAMEONLY 1220 number & name | NMBRNAME 1221 number if name | NMBRDEP 1222 name if number | NAMEDEP 1223 lineid | LINEONLY 1224 1225<br> 1226 1227>>> ##### Alphabetical list of related configuration options: 1228 1229>>> - ncidd.conf::cidalias 1230>>> - ncidd.conf::ignore1 1231>>> - ncidd.conf::lineid 1232>>> - ncidd.conf::regex 1233 1234 1235<!-- 1236[### FS1: Server Hangup Support] 1237--> 1238 1239>> ### <a name="fs1-hangup-support"></a> Server Hangup Support 1240>> 1241 1242>> At a high-level, there are two sets of procedures available to 1243 automatically hangup calls. Both are optional and one or both can be 1244 enabled at the same time. They are: 1245 1246>> * Internal Hangups. This is built in to the NCID server and uses the 1247 **ncidd.blacklist::<call name or number>** and 1248 **ncidd.whitelist::<call name or number>** files. 1249 1250>> * Hangup Extensions. This lets you use an external script or program. 1251 1252>> Internal Hangups are described below. 1253>> [Hangup Extensions are optional.](#fs1-hangup-ext) 1254 1255>> When Caller ID is received from a modem and if the caller name or 1256 number is in the blacklist file but not the whitelist file, hangup 1257 is automatic. 1258 1259>> NCID's support for automatic hangups is extensive and there is an 1260 entire section in the User Manual devoted to the subject (see the 1261 chapter "Using NCID"). Continue reading below for: 1262 1263>> - only API-specific topics 1264 1265>> - details of the *AT* commands sent for all hangup types 1266 1267>> - a summary of Internal Hangup-related configuration options in 1268>> **ncidd.conf** 1269 1270>> Internal Hangup support is optional in Feature Set 1. 1271 1272>> Clients implementing Feature Set 3: Client Job Support, can also 1273 be used to maintain the blacklist and whitelist. Such clients will 1274 also provide a way to force the server to reload these tables. 1275 1276>> When the server hangs up the line, it sends a 1277 <font color="red">HUP:</font> line to the clients and call log. The 1278 <font color="red">HUP:</font> line has the same layout as the 1279 <font color="red">CID:</font> line generated from the call, but 1280 with <font color="red">CID:</font> replaced by 1281 <font color="red">HUP:</font>. 1282 1283>>> ##### Internal Hangup Types 1284 1285 1286>>> If enabled by **ncidd.conf::hangup**, there are three types of hangups: 1287 1288 1289>>> - ##### Normal (required) 1290 1291>>>> When the server receives the Caller ID and if the name or number is 1292 in the blacklist file but not the whitelist file, the modem does a 1293 pickup, delays for one second and then does a hangup. 1294 1295<!-- 1296Sometimes (only sometimes) Pandoc doesn't like a table row to end with 1297nothing; Pandoc loses track of the fact that it is rendering a table. 1298So use ' '. ' ' also works. 1299--> 1300 1301>>>>> 1302 Action | Send this *AT* command 1303 ----------------|----------------------- 1304 PICKUP the line | ATH1 1305 delay 1 second | 1306 HANGUP | ATH0 1307 1308 1309>>> - ##### FAX (optional) 1310 1311>>>> When the server receives the Caller ID and if the name or number is 1312 in the blacklist file but not the whitelist file, the modem sets 1313 FAX mode, does a FAX answer, generates a FAX tone, delays for 10 1314 seconds, hangs up and resets to data mode. 1315 1316>>>>> 1317 Action | Send this *AT* command | Expected modem response 1318 -----------------|------------------------|------------------------ 1319 Set FAX Mode | AT+FCLASS=1 | OK 1320 * PICKUP the line| ATH1 | OK 1321 FAX Answer | ATA | 1322 delay 10 seconds | | 1323 HANGUP | ATH0 | OK 1324 Set DATA Mode | AT+FCLASS=0 | 1325 1326>>>> \* NOTE: **PICKUP** is a configuration option. Older modems may 1327fail to generate a FAX tone if there is a PICKUP. 1328 1329<br> 1330 1331>>> - ##### Announce (optional) 1332 1333>>>> When the server receives the Caller ID and if the name or number is 1334in the blacklist file but not the whitelist file, the modem sets 1335VOICE mode, answers the call, plays a recording, hangs up and 1336resets to data mode. 1337 1338>>>>> 1339 Action | Send this *AT* command | Expected modem response 1340 -----------------------------|------------------------|------------------------ 1341 Set VOICE Mode | AT+FCLASS=8 | OK 1342 Set speaker volume to normal | AT+VGT=128 | OK 1343 * Select compression method | AT+VSM=130 | OK 1344 Answer call | AT+VLS=1 | OK 1345 Set echo off | ATE0 | OK 1346 Select VOICE TRANSFER Mode | AT+VTX | CONNECT 1347 Send recording to modem | | 1348 Send end of recording | <DLE><ETX> | OK 1349 Set echo on | ATE1 | OK 1350 HANGUP | ATH0 | OK 1351 Set DATA Mode | AT+FCLASS=0 | 1352 1353>>>> \* NOTE: AT+VSM=130 is the default compression method used for the 1354Conexant CX93001 chipset used in a lot of modems. 1355 1356 1357 1358>>> ##### <a name="fs1-hangup-server-config-options"></a> Alphabetical list of related server configuration options: 1359 1360>>> - ncidd.conf::announce 1361>>> - ncidd.conf::audiofmt 1362>>> - ncidd.conf::blacklist 1363>>> - ncidd.conf::cidinput 1364>>> - ncidd.conf::hangup 1365>>> - ncidd.conf::ignore1 1366>>> - ncidd.conf::initcid 1367>>> - ncidd.conf::initstr 1368>>> - ncidd.conf::lockfile 1369>>> - ncidd.conf::pickup 1370>>> - ncidd.conf::regex 1371>>> - ncidd.conf::ttyclocal 1372>>> - ncidd.conf::ttyport 1373>>> - ncidd.conf::ttyspeed 1374>>> - ncidd.conf::whitelist 1375 1376<!-- 1377[### FS1: Modem-to-Server] 1378--> 1379 1380>> ### <a name="fs1-modem2server"></a> Modem-to-Server 1381 1382>>> In the US, telcos transmit the Caller ID between the first and 1383second rings. Telcos in other countries may transmit it before the first ring. 1384Nothing needs to be configured in NCID to accommodate this difference, 1385however, it is important that modems be configured for the 1386correct country code. The default is normally set based on where it is 1387purchased. If not, the user will need to do a one-time, manual 1388configuration of the country code, usually using the AT+GCI command. 1389 1390>> <a name="fs1-modem2server-ascii-format-cid"></a> ASCII Format Caller ID 1391 1392>>> This is a human-readable version of detected Caller ID. It is 1393controlled by setting **ncidd.conf::initcid**. Typical values are 1394"AT+VCID=1" or "AT#CID=1". Formatted Caller ID is the NCID default. 1395 1396>>> An example of a modem's caller ID output is shown below. The order 1397of the lines is unimportant and some of the lines may not be 1398present. For example, the MESG line is normally not emitted by modems. 1399 1400>>> There may or may not be a space before the '='. 1401 1402>>> The NMBR label may be DDN\_NMBR (Dialable Directory Number) instead, 1403>>> depending on the country. 1404 1405>>>> 1406 RING 1407>>>> 1408 MESG = 110101 1409 DATE = 0511 1410 TIME = 1852 1411 NMBR = 4075550000 or DDN_NMBR = 4075550000 1412 NAME = JOHN DOE 1413>>>> 1414 RING 1415 1416>>>> 1417 1418>> <a name="fs1-modem2server-ascii-hex-format-cid"></a> XDMF ASCII hex format Caller ID (SDMF, MDMF) (new in API 1.7) 1419 1420>>> This is a "XDMF ASCII hex" version of detected Caller ID. It is controlled 1421by setting **ncidd.conf::initcid**. Typical values are "AT+VCID=2" or 1422"AT#CID=2". This is the actual data stream supplied by telcos. Not all 1423modems support enabling unformatted output. 1424 1425>>> The XDMF format for Caller ID from modems is a long line in hexadecimal characters as 1426 *ASCII text*. XDMF is either MDMF or SDMF. 1427 1428>>> It is important to note that only *modems* configured for XDMF Caller ID send the output 1429 as *ASCII text*. 1430 1431>>> As long as the modem has been initialized with the appropriate 1432**ncidd.conf::initcid** string, the NCID server automatically detects 1433Formatted and Unformatted caller ID data streams. 1434 1435>>> <a name="fs1-modem2server-sdmf"></a> SDMF (Single Data Message Format) 1436allows telcos to supply the date, time and caller ID phone number only. 1437If the phone number is unavailable, a single letter in place of the 1438phone number will indicate the reason: A = anonymous, O = out of area, 1439P = private. 1440 1441>>> Here is the SDMF equivalent of the above Formatted Caller ID: 1442 1443>>>> 1444 RING 1445>>>> 1446 041230353131313835323430373535353030303059 1447>>>> 1448 RING 1449 1450>>>> 1451 1452>>> The hexadecimal string is parsed as follows: 1453 1454>>>> 1455 0412 3035313131383532 34303735353530303030 59 1456>>>> 1457 Type Len ASCII Hex DATA 1458 04h 12h SDMF Call 1459 DateTime 3035 3131 3138 3532 '05111852' 1460 Number 3430 3735 3535 3030 3030 '4075550000' 1461 59h Checksum 1462 1463>>> The data consists of: 1464 1465>>> - a one-byte (two hexadecimal characters) parameter type 1466('04' means SDMF in this example) 1467>>> - a one-byte (two hexadecimal characters) 1468parameter length ('12' in hex, 18 in decimal) excluding the checksum byte 1469>>> - zero or more bytes of parameter data (date, time, phone number). 1470>>> - a one-byte (two hexadecimal characters) checksum value calculated 1471as the two's complement of the modulo 256 sum of all preceding bytes. 1472 1473>>> <a name="fs1-modem2server-mdmf"></a> MDMF (Multiple Data Message 1474Format) is an enhanced version of SDMF that adds the caller ID name and 1475can also include the data for other telco services (e.g. voicemail 1476message waiting). Most telcos now use MDMF. 1477 1478>>> Whereas SDMF consists of a single parameter "block" followed by a 1479checksum, MDMF consists of multiple parameter blocks followed by a 1480checksum. 1481 1482>>> Here is the MDMF equivalent of the above Formatted Caller ID: 1483 1484>>>> 1485 RING 1486>>>> 1487 802001083035313131383532020A3430373535353030303007084A4F484E20444F4584 1488>>>> 1489 RING 1490 1491>>>> 1492 1493>>> The hexadecimal string is parsed as follows: 1494 1495>>>> 1496 8020 01083035313131383532 020A34303735353530303030 1497 07084A4F484E20444F45 84 1498>>>> 1499 Type Len ASCII Hex DATA 1500 80h 20h MDMF Call 1501 01h 08h DateTime 3035 3131 3138 3532 '05111852' 1502 02h 0Ah Number 3430 3735 3535 3030 3030 '4075550000' 1503 07h 08h Name 4A4F 484E 2044 4F45 'JOHN DOE' 1504 84h Checksum 1505 1506>>> Here, '80' indicates MDMF, '20' is 32 in decimal for the number of 1507bytes to follow excluding the checksum byte. 1508 1509>>> For a good overview of SDMF and MDMF, 1510see: http://melabs.com/resources/callerid.htm 1511Note that not all of the checksums shown on the above page are correct 1512and the site's owner has been notified. 1513 1514<!-- 1515[## Feature Set 1: Optional Server Extensions] 1516--> 1517 1518>> ### <a name="fs1-server-ext"></a> Optional Server Extensions 1519 1520 1521>> A Server Extension is an optional external script or program that is 1522 called by ncidd to perform a function and return a result. Server 1523 Extensions are a way for users to add functionality to NCID without 1524 requiring changes to NCID itself, especially when the functionality is 1525 atypical and would not have a broad appeal to other NCID users. 1526 1527>> Server Extensions are isolated from the main NCID distribution and 1528 because of this they do not normally require any changes when NCID is 1529 upgraded to a later version. 1530 1531>> One of the design philosophies that has always existed with NCID is to 1532 accept incoming caller ID as quickly as possible and to send it to all 1533 connected clients as quickly as possible. With a Server Extension, there 1534 is a risk that executing one can impact performance. For this reason, 1535 users are cautioned to create Server Extensions that are optimized for 1536 fast execution. 1537 1538>> The overall theory of operation is that ncidd will pass call info to 1539 the Server Extension, it will do whatever processing is desired and 1540 return back to ncidd some sort of result. 1541 1542>> In order for ncidd to use Server Extensions, there is a minimal amount 1543 of configuration information required in **ncidd.conf**. Typically this 1544 consists of a setting to enable/disable the Server Extension and a 1545 setting to tell ncidd the Server Extension name. Server Extensions 1546 may have specific options that also need to be in **ncidd.conf**. 1547 1548>> Beyond the minimal info needed to make ncidd aware of the Server Extension, 1549 there is no reason that a Server Extension could not have its own 1550 configuration file. 1551 1552>> You can use any scripting or programming language desired, however, if 1553 it is a scripting language and not a compiled binary, the first line 1554 must use the normal Unix convention of a "#!" path to the interpreter. 1555 1556>> Examples: 1557>> 1558>>> #!/bin/bash 1559>>> #!/usr/bin/perl 1560 1561>> Currently the only Server Extension supported is the Optional Server Hangup 1562>> Extension. 1563 1564<!-- 1565[### FS1: Optional Server Hangup Extension] 1566--> 1567 1568>>> #### <a name="fs1-hangup-ext"></a> Optional Server Hangup Extension 1569 1570>>> You might want to implement a Hangup Extension if you want additional 1571 or alternative call termination checking beyond the basic Internal Hangup 1572 that's implemented with the **ncidd.blacklist** and **ncidd.whitelist** 1573 files. All **ncidd.conf::hangup** modes (normal, fax, announce) are supported. 1574 1575>>> One advantage that Hangup Extensions have over the basic Internal Hangup 1576 is the ability to associate a different **ncidd.conf::announce** file for 1577 every caller ID number or name. 1578 1579>>> The Hangup Extensions script determines what calls to hang up on. It does not use 1580 **ncidd.blacklist** but does use **ncidd.whitelist**. If the call is in 1581 **ncidd.whitelist** or if the basic Internal Hangup is enabled and has hung up on the call, 1582 the hangup script is not executed. 1583 1584>>> Alphabetical list of related server configuration options: 1585 1586>>> - ncidd.conf::hupmode 1587>>> - ncidd.conf::hupname 1588>>> - ncidd.conf::huprmd 1589 1590>>> The **ncidd.conf::hupname** file must begin with `hangup-`. 1591 1592>>> ncidd passes one string of call info as a single command line argument. 1593 It passes it at the point just prior to changing the line type from 1594 <font color="red">CID:</font> to <font color="red">HUP:</font>. ncidd 1595 must wait for the Hangup Extension response data before continuing. 1596 1597>>> The string of call info has the following format and is subject to 1598 the rules described in [About field pairs and line types](#about-pairs). 1599 1600>>>> `*DATE*<date>*TIME*<time>*LINE*<lineid>*NMBR*<number>*NAME*<name>*MODE*<hupmode>*` 1601 1602>>> It has the following fields: 1603 1604>>>> 1605 <label>\*<data>\* | Description 1606 ------------------|:-------------------------------------------------------- 1607 DATE\*date\* | where date is [mmddyyyy or ddmmyyyy](#gen-datetime), m = month, d = day, y = year 1608 TIME\*time\* | where time is [hhmm in 24-hour format](#gen-datetime), h = hour, m = minute 1609 LINE\*lineid\* | where lineid is a [string of characters](#gen-text), NO-LINE or - 1610 NMBR\*number\* | where number is a [string of characters](#gen-text), NO-NUMBER or - 1611 NAME\*name\* | where name is a [string of characters](#gen-text), NO NAME or - 1612 MODE\*hupmode\* | where hupmode is in the range of 1 to 3 1613 1614>>> Data to be passed back from the Hangup Extension to ncidd must be sent to STDOUT. 1615 1616>>> Format 1: 1617>>> 1618>>>> One of these optional lines, depending on the value of hupmode: 1619>>>> 1620>>>>> Using HUPMODE 1 - Normal Hangup 1621>>>>> Using HUPMODE 2 - FAX Hangup 1622>>>>> Using HUPMODE 3 - VOICE Hangup 1623 1624>>>> HangupReason:<your optional custom hangup reason> 1625>>>> hangup|OK 1626 1627>>> Format 2, when **ncidd.conf::hupmode** = 3 you can specify an optional voice file: 1628>>> 1629>>>> One of these optional lines, depending on the value of hupmode: 1630>>>> 1631>>>>> Using HUPMODE 1 - Normal Hangup 1632>>>>> Using HUPMODE 2 - FAX Hangup 1633>>>>> Using HUPMODE 3 - VOICE Hangup 1634 1635>>>> Recording:<file name or full path> 1636>>>> HangupReason:<your optional custom hangup reason> 1637>>>> hangup|OK 1638 1639>>> Format 3, when **ncidd.conf::hupmode** != 3 and hupmode 3 is required: 1640>>> 1641>>>> One of these optional lines, depending on the value of hupmode: 1642>>>> 1643>>>>> Using HUPMODE 1 - Normal Hangup 1644>>>>> Using HUPMODE 2 - FAX Hangup 1645>>>>> Using HUPMODE 3 - VOICE Hangup 1646 1647>>>> Voice hangup is required 1648>>>> abort 1649 1650>>> (New in API 1.6) You can specify an optional reason that the Hangup Extension 1651>>> is terminating the call by sending the `HangupReason:` line. When the 1652>>> ncidd server detects this line, it will append <your optional custom 1653>>> hangup reason> to the NAME appearing in the <font color="red">HUP:</font> 1654>>> line. The `HangupReason:` line must be sent prior to the `hangup` line. 1655 1656>>> The `Recording:` line must be sent prior to the `hangup` line. If it 1657 is not present, it will default to the voice file in **ncidd.conf::huprmd**. 1658 If **ncidd.conf::huprmd** is not defined, the **ncidd.conf::announce** voice file will be 1659 used. 1660 1661>>> All data sent to STDOUT by the Hangup Extension will be saved to ncidd.log. 1662 1663>>> If and only if `hangup` is passed back to ncidd will the call be immediately 1664 terminated. Passing back `OK` is not required (no response at all is 1665 also acceptable) but it is suggested because you'll be able to see it 1666 in **ncidd.log**. 1667 1668<!-- 1669[### FS1: Optional NetCallerID Device-to-Server] 1670--> 1671 1672>> ### <a name="fs1-netcid2server"></a> Optional NetCallerID Device-to-Server 1673 1674>> The NetCallerID serial device outputs the Caller ID on a single line 1675with the following format: 1676 1677>>> `###DATE<datetime>...NMBR<number>...NAME<words>+++\r` 1678 1679>> The NetCallerID line has the following fields: 1680 1681<br> 1682 1683>>> 1684 <label><data> | Description 1685 ------------------|:-------------------------------------------------------- 1686 \#\#\# | start of the information part of the message being sent to the server 1687 DATEdatetime | where datetime is [mmddhhmm or ddmmhhmm](#gen-datetime), m = month, d = day, h = hour, m = minute 1688 ... | field separator 1689 NMBRnumber | where number is the phone number 1690 ... | field separator 1691 NAMEwords | where words is a name or -UNKNOWN CALLER- or -MSG OFF- or similar 1692 +++ | end of the information part of the message 1693 1694>> Examples: 1695 1696>>> 1697 ###DATE03301423...NMBR4075551212...NAMEWIRELESS CALL+++\r 1698 ###DATE03301423...NMBR...NAME-UNKNOWN CALLER-+++\r 1699 ###DATE03301423...NMBR...NAME+++\r 1700 ###DATE...NMBR...NAME-MSG OFF-+++\r 1701>> 1702 1703<!-- 1704[### FS1: Optional TCI Device-to-Server (new in API 1.1)] 1705--> 1706 1707>> ### <a name="fs1-tci2server"></a> Optional TCI Device-to-Server (new in API 1.1) 1708 1709>> Serial **TCI** devices output a single line using the **Telephone 1710Collectors International** output standard. 1711 1712>> To make sure the text line is from a TCI device, the server tests to 1713make sure all of the following are true: 1714 1715 1716>>> line length > 30 characters 1717>>> position 0 is a digit 1718>>> position 9 is a '/' 1719>>> position 24 is an 'M' 1720 1721>> The TCI line has the following fields: 1722 1723>>> 1724 Positions | Length | Description 1725 ---------:|:------:|:----------- 1726 0-1 | 2 | LINE 1727 7-11 | 5 | DATE 1728 17-24 | 8 | TIME 1729 29-43 | 15 | NUMBER 1730 55-69 | 15 | NAME 1731 1732 1733>> Example: 1734 1735>>> 1736 01 9/03 2:25 PM 806-672-1767 WIRELESS CALLER 1737 0123456789012345678901234567890123456789012345678901234567890123456789 1738 1 2 3 4 5 6 1739 1740>> **NOTE:** 1741 1742>>> All fields except NAME are right justified. Five spaces separate each field, 1743>>> except NUMBER and NAME fields which are separated by 11 spaces. 1744>> 1745> 1746<!-- 1747[### FS1: CLIENT IMPLEMENTATION] 1748--> 1749> 1750> ### <a name="fs1-client-impl"></a> CLIENT IMPLEMENTATION 1751 1752>> - connect to port 3333 or whatever port is specified in server 1753 configuration 1754 1755>> - receive a <font color="red">200</font> server version text message 1756 1757>> - receive a <font color="red">210</font> server API version text message 1758 1759>> - (New in API 1.5) send zero or more <font color="red">HELLO:</font> lines 1760 1761>> - if no call log is sent by the server, receive a <font 1762color="red">251 Call log not sent</font> or a <font color="red">252 Call 1763log empty</font> or a <font color="red">253 No call log</font> message 1764 1765>> - if a call log is sent by the server, it: 1766 1767>>> - may contain <font color="red">CIDLOG:</font> text lines to be parsed and displayed 1768 1769>>> - may contain <font color="red">HUPLOG:</font> text lines to be parsed and displayed 1770 1771>>> - may contain <font color="red">LOG:</font> text lines which must be ignored 1772 1773>>> - may contain <font color="red">MSGLOG:</font> text lines to be parsed and displayed 1774 1775>>> - will end with a <font color="red">250 End of call log</font> message 1776 1777>> - receive zero or more <font color="red">OPT: <option></font> lines. 1778 1779>>> ###### New in API 1.3 1780>>> 1781>>>> Unless otherwise noted, all <font color="red">OPT:</font> lines output by 1782 the server are for informational and troubleshooting purposes 1783 only. Clients can optionally make use of them by giving the user a 1784 way to display them. Otherwise, clients are not required to display 1785 them, do not need to take any action on them and can safely ignore them. 1786 See also [Feature Set 1 <font color="red">OPT:</font> definition](#line-type-opt) 1787 for more information. 1788 1789>>>> If a client wants to optionally display the <font color="red">OPT:</font> 1790 lines then it will need to do the following: 1791 1792>>>> - Retrieve all <font color="red">OPT:</font> lines during the initial 1793 connection to the server. 1794 1795>>>> - Have a way for users to easily view the <font color="red">OPT:</font> lines. 1796 They can be displayed however is convenient for the programming language the 1797 client is written in. Displaying the leading <font color="red">OPT:</font> 1798 text is optional, but the text following <font color="red">OPT:</font> 1799 must be shown. 1800 1801>>>> - Handle <font color="red">OPT: hangup</font> (i.e., with no 1802 dash-value) in order to accommodate servers that are not yet compliant 1803 with API 1.3. 1804 1805>>>> - Handle <font color="red">OPT: regex</font> (i.e., with no 1806 dash-value) in order to accommodate servers that are not yet compliant 1807 with API 1.7. 1808 1809 1810>>>> - Show "none" if no <font color="red">OPT:</font> lines were received. 1811 1812>>>> It is suggested, but not required: 1813 1814>>>> - That the lines be shown in a vertical list. 1815 1816>>>> - That user-friendly text be shown to allow easy interpretation of 1817 the setting. 1818 1819>>>> - That the lines be shown in a Help Menu. 1820 1821>>>> Examples below show <font color="red">OPT: hangup</font> for a 1822 pre-API 1.3 server and <font color="red">OPT: hangup-3</font>, even 1823 though they won't both be generated by the same server. Similarly 1824 for a pre-API 1.7 server, <font color="red">OPT: regex</font> and 1825 <font color="red">OPT: regex-2</font> won't both be present. 1826 1827>>>> Minimum suggested examples: 1828 1829>>>> 1830 Server-enabled options: 1831 OPT: hangup 1832 OPT: hangup-3 1833 OPT: hupmode-2 1834 OPT: ignore1 1835 OPT: regex 1836 OPT: regex-2 1837 OPT: LineIDS: LandLine VoIP 1838 1839>>>> or 1840 1841>>>> 1842 Server-enabled options: 1843 hangup 1844 hangup-3 1845 hupmode-2 1846 ignore1 1847 regex 1848 regex-2 1849 LineIDS: LandLine VoIP 1850 1851>>>> or 1852 1853>>>> 1854 Server-enabled options: 1855 none 1856 1857>>>> Ideal suggested examples showing all options: 1858 1859>>>> 1860 Server-enabled option| Description 1861 ---------------------| ----------- 1862 none | 1863 hangup|hangup-1 | Internal Hangup Mode 1: Terminate Blacklisted Call 1864 hangup-2 | Internal Hangup Mode 2: Generate FAX Tone and Terminate Blacklisted Call 1865 hangup-3 | Internal Hangup Mode 3: Play Announcement and Terminate Blacklisted Call 1866 hupmode-1 | Hangup Extension Mode 1: Terminate Blacklisted Call 1867 1868<br> 1869 1870>>>> 1871 Server-enabled option| Description 1872 ---------------------| ----------- 1873 hupmode-2 | Hangup Extension Mode 2: Generate FAX Tone and Terminate Blacklisted Call 1874 hupmode-3 | Hangup Extension Mode 3: Play Announcement and Terminate Blacklisted Call 1875 ignore1 | Server Ignores Leading 1 for Calls/Aliases 1876 regex|regex-1 | Use POSIX Extended Regular Expressions for Server List Matching 1877 regex-2 | Use Perl Regular Expressions for Server List Matching 1878 LineIDS: LandLine VoIP | Available lines for dialing numbers 1879 (anything else) | Unknown/invalid 1880 1881>> - receive a <font color="red">300 End of server startup</font> message 1882 1883>> - possibly receive a <font color="red">CIDINFO:</font> line at each 1884ring or just at the end of the call 1885 1886>> - possibly receive a <font color="red">CID:</font> line whenever a 1887call is received 1888 1889>> - possibly receive an <font color="red">HUP:</font> line whenever a 1890call is automatically terminated 1891 1892>> - clients are allowed to send a text message to the server using a 1893 <font color="red">MSG:</font> line 1894 1895>> - clients are allowed to connect and disconnect as they please 1896 1897>>> - (New in API 1.6) possibly send an optional <font color="red">GOODBYE</font> 1898 (note that there is no trailing colon) line to the server to close the 1899 connection 1900 1901>> - possibly send a <font color="red">\\n (newline)</font> to the server 1902 to determine if the server is still available. 1903 1904>> - (New in API 1.4) clients must always ignore line types that begin 1905>> with "+" (e.g., <font color="red">+CID:</font>, <font color="red">+CIDINFO:</font>) 1906>> because these represent call activity from a [Forwarding Gateway](#fs2-fwdgw) 1907>> that are processed only by the NCID server 1908 1909<!-- 1910[### FS1: Client-to-Server] 1911--> 1912 1913>> ### <a name="fs1-client2server"></a> Client-to-Server 1914 1915>> - <a name="line-type-newline"></a><font color="red">\\n (newline)</font> 1916 1917>>> Clients are allowed to send a <font color="red">\\n (newline)</font> 1918 to the server to determine if the server is still available. It 1919 should be sent only after at least 15 minutes of no server activity. 1920 There is no server response, however, the server will log this action 1921 as "Client xxx sent empty line." It is up to the client to check to 1922 see if sending a <font color="red">\\n (newline)</font> results in 1923 an error and take appropriate action (e.g., try to reconnect to the 1924 server). 1925 1926>>> If a client needs a more robust way of making sure the server is 1927 still available by requiring a server response, 1928 implement [Feature Set 4: Acknowledgment Support](#fs4-ack-support). 1929 1930>> - <a name="line-type-goodbye-client"></a> (New in API 1.6) <font color="red">GOODBYE</font> 1931 (note that there is no trailing colon) 1932 1933>>>- This optional line type allows the client to force a graceful disconnect 1934 from the server, rather than relying on the server to disconnect due 1935 to a connection timeout or error. This is an experimental feature to 1936 allow a simple register/unregister of clients using alternative 1937 connection protocols (e.g., a RESTful interface). 1938 1939>> - <a name="line-type-hello-client"></a><font color="red">HELLO: IDENT: <ident></font> <br> 1940 <font color="red">HELLO: CMD: <command></font> 1941 1942>>>- <font color="red"><ident></font> is any freeform text, upper 1943 and/or lowercase and any number of words separated by spaces. It is used 1944 to identify the client. 1945 1946>>>>- Only one <font color="red"><ident></font> line is expected but 1947 this is not strictly enforced. 1948 1949>>>>- The recommended client <font color="red"><ident></font> contents are: 1950 1951>>>>> <client> <program name> <version number> 1952 1953>>>>> *or* 1954 1955>>>>> (New in API 1.6) 1956 1957>>>>> <client> <[hostname/]program name> <version number> [OUT] 1958 1959>>>>- A server has the option of logging or displaying the <font color="red"><ident></font> string as clients 1960 connect and disconnect. 1961 1962>>>> New in API 1.6 1963 1964>>>>- *hostname* is optional, but if present it should end with a trailing 1965 slash and be followed immediately by the program name. 1966 1967>>>>- The presence of the special uppercase text *[OUT]* following the version 1968 in the <font color="red"><ident></font> string is used 1969 in [Feature Set 2: Gateway Support](#line-type-hello-gw) 1970 and [Feature Set 3: Client Job Support](#line-type-req-dial) to tell the 1971 server that the client or gateway will be generating <font color="red">OUT:</font> 1972 lines. For more information, [go to <font color="red">REQ: DIAL</font>](#line-type-req-dial). 1973 1974>>>- <font color="red"><command></font> controls a 1975 server setting or action. There can only be one <font color="red"><command></font> per line 1976 and unless otherwise indicated, commands are always in lowercase. 1977 1978>>>- Multiple lines are permitted. 1979 The order of <font color="red">IDENT: <ident></font> and 1980 <font color="red">CMD: <command></font> lines does not matter. 1981 1982>>>- <font color="red">HELLO:</font> line types are sent only when 1983 a connection is first established. The server delays on connect after 1984 sending a <font color="red">210</font> line in order give a client the opportunity to send the optional 1985 <font color="red">HELLO:</font> lines. To clarify, 1986 <font color="red">HELLO:</font> line types must be sent by the client 1987 immediately after receiving a <font color="red">210</font> line. 1988 1989>>>- Any <font color="red">HELLO:</font> line type received after the server 1990 starts sending the call log is handled as an unknown line type. 1991 1992>>>- An example client connection start-up looks like this: 1993>>> 1994>>>> 200 Server: ncidd (NCID) x.x 1995>>>> 210 API x.x Feature Set x x x x ... 1996>>>> HELLO: IDENT: client ncid x.x.x 1997>>>> HELLO: CMD: no_log 1998>>>> HELLO: ... 1999>>>> 251 Call log not sent: /var/log/cidcall.log 2000>>>> OPT: hangup-1 2001>>>> OPT: ... 2002>>>> 300 End of connection startup 2003 2004>>>- Unlike most other line types, <font color="red">HELLO:</font> line types 2005 must NOT be sent to clients. 2006 2007>>>- At present, there are two commands: 2008>>> 2009>>>> HELLO: CMD: no_log 2010>>>> HELLO: CMD: send_log 2011 2012>>>> The purpose of the <font color="red">no_log</font> command is to temporarily override the server's 2013 **ncidd.conf::send cidlog** setting. By doing so, the client or gateway 2014 can finish connecting much quicker because no call log will be sent. 2015 The override is maintained only for the currently connecting client 2016 or gateway and only for the duration of its connection startup. 2017 2018>>>> (New in API 1.6) If **ncidd.conf::send cidlog** is enabled and <font color="red">HELLO: CMD: no_log</font> 2019 is sent to the server, instead of sending the log, the server must respond with 2020 <font color="red">251 Call log not sent</font>. The connection startup 2021 continues normally, ending with <font color="red">300 End of connection startup</font>. 2022 It is critical that the server clears this temporary override so that 2023 it is not carried over to future connections. 2024 2025>>>> (New in API 1.6) If **ncidd.conf::send cidlog** is *not* enabled and <font color="red">HELLO: CMD: send_log</font> 2026 is sent to the server, the server must try to send the log and respond with either 2027 <font color="red">250 End of call log</font>, <font color="red">252 Call log empty</font>, 2028 or <font color="red">253 No Call log</font>. The connection startup 2029 continues normally, ending with <font color="red">300 End of connection startup</font>. 2030 It is critical that the server clears this temporary override so that 2031 it is not carried over to future connections. 2032 2033>>>> The <font color="red">no_log</font> command has no effect on the Feature Set 3 2034 <font color="red">REQ: REREAD</font> Client Job that causes the call log to be resent. 2035 2036>>>> (New in API 1.6) The <font color="red">send_log</font> command has no effect on 2037 <font color="red">REQ: REREAD</font> either. 2038 2039 2040>> - <a name="line-type-msg-client"></a><font color="red">MSG:</font> (client output) 2041 2042>>> A text line containing a user-generated message that is sent to the 2043 server, saved in the call log and then forwarded to all listening clients. 2044 2045>>> It has the [{MSGTYPES} Category Structure for Client/Gateway Output Lines](#comm-msgtypes-client-gw). 2046 2047>>> Example: 2048 2049>>>> 2050 MSG: This is a user message ###DATE ... 2051 2052<!-- 2053[### FS1: Optional Client-to-Module] 2054--> 2055 2056>> ### <a name="fs1-client2module"></a> Optional Client-to-Module 2057 2058>> When the client is configured to use an output module, it splits the 2059single server call line into eight lines for passing via standard input 2060to the output module. 2061 2062>>> `<date>\n<time>\n<number>\n<name>\n<lineid>\n<input type>\n<""|message>\n<message type>\n` 2063 2064<br> 2065<br> 2066<br> 2067<br> 2068<br> 2069<br> 2070 2071>> The contents of each line are as follows: 2072 2073>>> 2074 Line | Field | Description 2075 ----:| ------------------------------|-------------------------------------------------------- 2076 1 | date mm/dd/yyyy or dd/mm/yyyy | date of either the call or message <br>where m = month, d = day, y = year 2077 2 | time hh:mm or hh:mm am/pm | Time of either the call or message <br>where h = hour, m = minute 2078 3 | number | Number of either the call or message 2079 4 | name | Who made the call 2080 5 | lineid | Lineid of either the call or message 2081 6 | input type | One of the <font color="red">\{CALLTYPES\}</font> or <font color="red">\{MSGTYPES\}</font> designated Feature Set 1 in the [Categories table](#comm-table) 2082 7 | message | Message, or blank for a call 2083 8 | message type | If <input type> indicates a call then <message type> will be null. Otherwise, <message type> will be IN, OUT or -. 2084>> 2085>> 2086 2087<!-- 2088[### FS1: Optional Client-to-TiVo Display] 2089--> 2090 2091>> 2092>> ### <a name="fs1-client2tivo"></a> <strike>Optional Client-to-TiVo Display</strike> <font color="dimgray">(Removed in API 1.6)</font> 2093 2094>> <strike>If the TiVo (--tivo|-T) option is given on the command line when 2095launching the ncid client, or the <font color="red">TivoFlag</font> is 2096set to 1 in <font color="red">ncid.conf</font>, the output is two lines. 2097The first line contains the Caller ID name and number. The second line 2098contains the type of call and a telephone lineid. If the lineid is 2099blank, then there is no second line: 2100 2101 2102>>> 2103 PASADENA, CA (800)555-1212 2104>>> 2105 PASADENA, CA (800)555-1212 2106 CID POTS 2107</strike> 2108 2109<!-- 2110[## Feature Set 2: Gateway Support] 2111--> 2112 2113## <a name="fs2-gw-support"></a> Feature Set 2: Gateway Support 2114 2115<!-- 2116[### FS2: SERVER IMPLEMENTATION] 2117--> 2118 2119> ### <a name="fs2-server-impl"></a> SERVER IMPLEMENTATION 2120 2121>> If you want to implement a server to communicate with NCID clients 2122and gateways: 2123 2124>> - implement a Feature Set 1 server 2125 2126>> - detect gateways as they come and go 2127 2128>> - if a gateway sends a line prefixed with <font color="red">CALL:</font>, 2129process it to generate a <font color="red">{CALLTYPES}</font> line 2130 2131>> - if a gateway sends a line prefixed with <font 2132color="red">CALLINFO:</font>, process it to generate: 2133 2134>>> - an <font color="red">END:</font> line and 2135 2136>>> - a <font color="red">CIDINFO:</font> line with <font 2137color="red">CANCEL</font> if the ring count is -1, or 2138 2139>>> - a <font color="red">CIDINFO:</font> line with <font 2140color="red">BYE</font> if the ring count is -2, or 2141 2142>>> - a <font color="red">CIDINFO:</font> line with <font 2143color="red">BUSY</font> if the ring count is -3 2144 2145>> - if a gateway sends a [{MSGTYPES} Client/Gateway Output Line](#comm-msgtypes-client-gw), 2146process it to generate a [{MSGTYPES} Server Output Line](#comm-msgtypes-server) 2147(normally this is just replacing <font color="red">\#\#\#</font> with 2148<font color="red">\*\*\*</font>) 2149 2150>> - (New in API 1.6) examine one or more 2151 <font color="red">HELLO: IDENT: <ident></font> lines 2152 sent by clients and gateways to see if the 2153 <font color="red"><ident></font> string identifies certain 2154 client-specific or gateway-specific features that the server 2155 needs to be aware of. 2156 2157<!-- 2158[### FS2: XDMF Input] 2159--> 2160 2161>> ### <a name="fs2-xdmf-input"></a> XDMF input 2162 2163>>> The XDMF gateway (xdmf2ncid) accepts either hex input from a modem or binary input from a device. 2164 2165>>> Devices such as the CTI Comet USB or the Holtek HT9032D based PSTN Caller ID module output XDMF 2166 (MDMF or SDMF) Caller ID with the same parameter structure as modems, but do so as binary data 2167 and do not emit RING lines. 2168 2169>>> Set xdmf2ncid::ht9032 = 0 for input from a Comet or modem. 2170 Set xdmf2ncid::ht9032 = 1 for input from a Holtek HT9032D module. 2171 2172>>> The data consists of: 2173 2174>>> - a one-byte parameter type for MDMF or SDMF 2175>>> - a one-byte parameter length excluding the checksum byte 2176>>> - zero or more bytes of parameter data (date, time, phone number) 2177>>> - a one-byte checksum value calculated as the two's complement of the modulo 256 sum 2178 of all preceding bytes. 2179 2180>>> Refer to [XDMF ASCII Format Caller ID](#fs1-modem2server-ascii-hex-format-cid) for: 2181 2182>>> - ASCII Hex data from modems 2183>>> - Description of SDMF and an example of the format 2184>>> - Description of MDMF and an example of the format 2185 2186>>> An SDMF binary string, same as the example SDMF string in ASCII Hex: 2187 2188 0412 05111852 4075550000 59 2189 2190 Type Len DATA FORMATTED 2191 04h 12h SDMF Call 2192 DateTime 05111852 05/11 18:52 2193 Number 4075550000 407-555-0000 2194 59h Checksum 2195 2196>>> An MDMF binary string, same as the example MDMF string in ASCII Hex: 2197 2198 8020 05111852 020A4075550000 07084A4F484E20444F45 84 2199 2200 Type Len DATA FORMATTED 2201 80h 20h MDMF Call 2202 01h 08h DateTime 05111852 05/11 18:52 2203 02h 0Ah Number 4075550000 407-555-0000 2204 07h 08h Name 4A4F 484E 2044 4F45 JOHN DOE 2205 84h Checksum 2206 2207>> <a name="fs2-xdmf-input-ht9032-op-mode"></a> Holtek HT9032D operation mode 2208 2209>>> The Holtek HT9032D based PSTN Caller ID module also outputs random data. In between this noise is 2210 the actual XDMF data, preceded by 27 or 28 x 0x55 (U chars), with a final random character. 2211 2212>>> The following depicts the output from the Holtek HT9032D module: 2213 2214>>> **<RANDOM DATA><27 or 28 U's><RANDOM CHARACTER><MDMF PACKET><RANDOM DATA>** 2215 2216>>> The XDMF packet format: **<XDMF start><length><data><checksum>** 2217 2218>>> The XDMF packet length is used to strip the random data that follows the XDMF packet checksum. 2219 2220>>> For a good overview see: [Testing LinkSprite Caller ID Module (based on HT9032) with a PC](https://bigdanzblog.wordpress.com/2015/05/22/testing-linksprite-caller-id-module-based-on-ht9032-with-a-pc/). 2221 2222>>> The logic for determining data and noise packets takes one or two reads. 2223 2224>>> - Read1: 2225 Must either contain 10 or more U's to indicate the start of a XDMF packet, or end in a U to 2226 indicate the start of a possible XDMF packet. If neither, read1 is random data and is ignored. 2227 2228>>> - Read2: 2229 Needed if read1 contains 10 or more U's but does not contain any XDMF packet, if read1 2230 ends in a U or if read1 contains a partial XDMF data packet. 2231 2232>>> If the number of U's between read1 and read2 is still less than 10, both read1 and read2 are 2233 random characters and ignored. A log entry indicates this. 2234 2235<!-- 2236[### FS2: Server Output Lines] 2237--> 2238 2239>> ### <a name="fs2-server-output"></a> Server Output Lines 2240 2241>> - <a name="line-type-blk"></a><font color="red">BLK:</font> 2242 2243>>> When a call is automatically blocked, a <font 2244color="red">BLK:</font> (Call Blocked) line is created. A blocked call 2245is one where the CID device (e.g., Whozz Calling Ethernet Link devices) 2246does not pass an incoming call through to connected telephones. The 2247calling party simply hears the line ringing. Compare this with a 2248terminated (<font color="red">HUP:</font>) call where the calling party 2249hears the line disconnect and may or may not hear the line ringing at 2250all. 2251 2252>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes). 2253 2254>> - <a name="line-type-end"></a><font color="red">END:</font> 2255 2256>>> An end-of-call text line. It is generated from the <font 2257color="red">CALLINFO:</font> text line from a gateway. It provides 2258information that can be used for call accounting. 2259 2260 2261>>>> `END: 2262*HTYPE*<ec>*DATE*<date>*TIME*<time>*SCALL*<dt>*ECALL*<dt>*CTYPE*<io>*LINE*<lineid>*NMBR*<number>*NAME*<name>*` 2263 2264>>> The <font color="red">END:</font> line has the following field pairs 2265(field label and field data): 2266 2267>>>> 2268 <label>\*<data>\* | Description 2269 ------------------|:-------------------------------------------------------- 2270 HTYPE\*ec\* | where ec = BYE or CANCEL 2271 DATE\*date\* | where date is [mmddyyyy or ddmmyyyy](#gen-datetime), m = month, d = day, y = year 2272 2273<br> 2274 2275>>>> 2276 <label>\*<data>\* | Description 2277 ------------------|:-------------------------------------------------------- 2278 TIME\*time\* | where time is [hhmm in 24-hour format](#gen-datetime), h = hour, m = minute 2279 SCALL\*date time\*| where start of call date is [mm/dd/yyyy](#gen-datetime), a space and time is [hh:mm:ss in 24-hour format](#gen-datetime), m = month, d = day, y = year, h = hour, m = minute, s=second 2280 ECALL\*date time\*| where end of call date is [mm/dd/yyyy](#gen-datetime), a space and time is [hh:mm:ss in 24-hour format](#gen-datetime), m = month, d = day, y = year, h = hour, m = minute, s=second 2281 CTYPE\*io\* | where io is either IN or OUT (this is not a pass through of the <font color="red">CALL:</font> CALLtype) 2282 LINE\*lineid\* | where lineid is a [string of characters](#gen-text), NO-LINE or - 2283 NMBR\*number\* | where number is a [string of characters](#gen-text), NO-NUMBER or - 2284 NAME\*name\* | where name is a [string of characters](#gen-text), NO NAME or - 2285 2286>> - <a name="line-type-mwi"></a><font color="red">MWI:</font> (new in API 1.7) 2287 2288>>> A voicemail message waiting text line. It is sent to the clients and saved 2289 in the call log when a Message Waiting Indicator is received. 2290 2291>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes), however, 2292 NAME and NMBR will have text. See the [<font color="red">CALL:</font> 2293 definition in the Gateway-to-Server section](#line-type-call). 2294 2295>>> Example for US telcos: 2296 2297>>>> 2298 MWI: *DATE*04172018*TIME*2005*LINE*HOME*NMBR*Voicemail*MESG*NONE* 2299 NAME*Message(s) Waiting* 2300 MWI: *DATE*04172018*TIME*2136*LINE*HOME*NMBR*Voicemail*MESG*NONE* 2301 NAME*No Messages Waiting* 2302 2303>>> Example for UK telcos: 2304 2305>>>> 2306 MWI: *DATE*04222018*TIME*1303*LINE*HOME*NMBR*Voicemail*MESG*NONE* 2307 NAME*1 Message Waiting* 2308 MWI: *DATE*04222018*TIME*1619*LINE*HOME*NMBR*Voicemail*MESG*NONE* 2309 NAME*5 Messages Waiting* 2310 MWI: *DATE*04232018*TIME*0839*LINE*HOME*NMBR*Voicemail*MESG*NONE* 2311 NAME*No Messages Waiting* 2312 2313>> - <a name="line-type-not-server"></a><font color="red">NOT:</font> 2314 2315>>> A notification text line of a smartphone message. It is sent to all 2316clients and saved in the call log. 2317 2318>>> It has the [{MSGTYPES} Category Structure for Server Output Lines](#comm-msgtypes-server). 2319 2320>>> Examples: 2321 2322>>>> 2323 NOT: PHONE 4012: PING Test notification ***DATE ... 2324 NOT: PHONE 7cd0: SMS from mail@nowhere.com ***DATE ... 2325 2326>> - <a name="line-type-out"></a><font color="red">OUT:</font> 2327 2328>>> An outgoing call text line. 2329 2330>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes). 2331 2332>> - <a name="line-type-pid"></a><font color="red">PID:</font> 2333 2334>>> A smartphone incoming Caller ID text line sent to NCID. It uses the 2335<font color="red">PID:</font> label instead of the <font color="red">CID:</font> 2336label because the ncid-page client output module can be configured to send 2337<font color="red">CID:</font> and <font color="red">MSG:</font> text lines to 2338smartphones. This could cause the same message to be sent back and forth 2339in an infinite loop if <font color="red">CID:</font> or 2340<font color="red">MSG:</font> were used. 2341 2342>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes). 2343 2344>> - <a name="line-type-put"></a><font color="red">PUT:</font> (new in API 1.7) 2345 2346>>> A smartphone outgoing Caller ID text line sent to NCID. It uses the 2347<font color="red">PUT:</font> label instead of the <font color="red">OUT:</font> 2348label. 2349 2350>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes). 2351 2352>> - <a name="line-type-rid"></a><font color="red">RID:</font> (new in API 1.7) 2353 2354>>> A Ring Back Caller ID text line. Ring back is a service offered by 2355 some telcos. On making a telephone call to a number that is engaged 2356 (busy), automatic ring back is a service provided by the telco whereby, 2357 when the called number becomes available, the caller is rung back, 2358 usually with a distinctive "ring back" ring. 2359 2360>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes). 2361 2362>> - <a name="line-type-wid"></a><font color="red">WID:</font> (new in API 1.1) 2363 2364>>> A Call Waiting Caller ID text line. 2365 2366>>> It has the [{CALLTYPES} Category Structure](#comm-calltypes). 2367 2368<!-- 2369[### FS2: GATEWAY IMPLEMENTATION] 2370--> 2371 2372 2373> ### <a name="fs2-gw-impl"></a> GATEWAY IMPLEMENTATION 2374 2375>> - connect to port 3333 or whatever port is specified in server 2376 configuration 2377 2378>> - receive a <font color="red">200</font> server version text message 2379 2380>> - receive a <font color="red">210</font> server API version text message 2381 2382>> - (New in API 1.5) immediately after receiving a <font color="red">210</font> line, 2383 send zero or more <font color="red">HELLO:</font> lines 2384 2385>> - if no call log sent, receive a <font color="red">251 Call log not 2386sent</font> or a <font color="red">252 Call log empty</font> or a <font 2387color="red">253 No call log</font> message (ignore) 2388 2389>> - if call log sent, receive a <font color="red">250 Call log 2390sent</font> message (ignore) 2391 2392>> - (New in API 1.5) if a server setting is being temporarily overridden by a 2393 <font color="red">HELLO: CMD: <command></font> line, 2394 clear the override so it will not apply to future connections. 2395 2396>> - receive zero or more <font color="red">OPT: <option></font> 2397lines (ignore) 2398 2399>> - receive a <font color="red">300 End of server startup</font> message 2400 2401>> - connect to the Caller ID service (SIP, YAC, etc) 2402 2403>> - when incoming CID information is obtained from the service, send the data to 2404the server in the <font color="red">CALL:</font> text line format with 2405<font color="red">IN</font> in the CALL<type> field 2406 2407>> - for all other <font color="red">{CALLTYPES}</font>, send the data to 2408 the server in the <font color="red">CALL:</font> text line format with 2409 the appropriate line type (e.g., <font color="red">WID</font>) 2410 in the CALL<type> field 2411 2412>> (note: "hangup" in the context below does not mean calls automatically 2413terminated by Internal Hangup or Hangup Extensions; it refers to hangups 2414triggered by a phone user or the telco): 2415 2416>> - if hangup is detected before answer, send the data to the server in the 2417 <font color="red">CALLINFO: CANCEL</font> text line format 2418 2419>> - if hangup is detected after answer, send the data to the server in the 2420 <font color="red">CALLINFO: BYE</font> text line format 2421 2422>> - if the gateway receives a notice of a smartphone message, send the 2423data to the server in the <font color="red">NOT:</font> text line format 2424with <font color="red">IN</font> in the MTYPE field 2425 2426>> - if the gateway sends a smartphone message, send the data to the 2427server in the <font color="red">NOT:</font> text line format with <font 2428color="red">OUT</font> in the MTYPE field (optional) 2429>> 2430>> 2431<!-- 2432[### FS2: Gateway-to-Server] 2433--> 2434>> 2435>> ### <a name="fs2-gw2server"></a> Gateway-to-Server 2436 2437>> When the gateway sends information to the server, it sends the data as 2438lines of text that start with a line label. This defines line types. The 2439current line labels are: 2440 2441>> - <a name="line-type-call"></a><font color="red">CALL:</font> 2442 2443>>> A gateway Caller ID text line. It is sent to the server and 2444converted into a <font color="red">CID:</font> or other 2445<font color="red">{CALLTYPES}</font> text line when a call is received. 2446The text line is comprised of field pairs, one contains the field name and the 2447following field contains the field data. Fields are separated by ..., 2448the first field starts after \#\#\# and the last field ends in +++: 2449 2450 2451>>>> `CALL: ###DATE<datetime>...CALL<type>...LINE<lineid>...NMBR<number>... 2452 NAME<name>+++` 2453 2454>>> The <font color="red">CALL:</font> line has the following field 2455pairs (field label and field data): 2456 2457>>>> 2458 <label><data> | Description 2459 ------------------|:-------------------------------------------------------- 2460 \#\#\# | start of the information part of the message being sent to the server 2461 DATEdatetime | where datetime is [mmddhhmm or ddmmhhmm ](#gen-datetime), m = month, d = day, h = hour, m = minute 2462 ... | field separator 2463 CALLtype | where type is IN, CID, or other <font color="red">\{CALLTYPES\}</font> 2464 ... | field separator 2465 LINElineid | where lineid is a [string of characters](#gen-text), NO-LINE or - 2466 ... | field separator 2467 NMBRnumber | where number is a [string of characters](#gen-text), NO-NUMBER or - 2468 ... | field separator 2469 2470<br> 2471 2472>>>> 2473 <label><data> | Description 2474 ------------------|:-------------------------------------------------------- 2475 NAMEname | where name is a [string of characters](#gen-text), NO NAME or - 2476 +++ | end of the information part of the message 2477 2478>>> - If the gateway is on a smartphone or connects to a smartphone, the 2479CALLtype must be <font color="red">PID</font> for incoming calls or 2480<font color="red">PUT</font> for outgoing calls. (<font color="red">PUT</font> 2481is new in API 1.7.) 2482 2483>>> - (New in API 1.7) If the telco transmits a Message Waiting Indicator, 2484the CALLtype must be <font color="red">MWI</font>. 2485 2486>>>> - The telco is not expected to supply DATEdatetime and NMBR so the 2487gateway must fill these in as follows: 2488 2489>>>>> - use current date and time for the DATEdatetime field 2490 2491>>>>> - use the text 'Voicemail' for NMBR 2492 2493>>>> - The gateway must fill in NAME depending on the kind of MWI sent by 2494the telco, which is usually one of two types: 2495 2496>>>>> - a simple on/off MWI, usually used by US telcos, in which case NAME 2497should contain the text 'Message(s) Waiting' or 'No Messages Waiting' 2498respectively. An "off" status would be sent only to transition from the 2499MWI being "on". 2500 2501>>>>> - a count of the messages waiting, usually used by UK telcos, in 2502which case NAME should have the text '1 Message Waiting', '2 Messages Waiting', 2503etc., up to the maximum of '255 Messages Waiting'. The text 'No Messages 2504Waiting' should be in NAME when there's a transition from one or more 2505messages waiting, to zero, after they have all been listened to. 2506 2507>>>> Example for US telcos: 2508>>>> 2509 CALL: ###DATE04172005...CALLMWI...LINEHOME...NMBRVoicemail... 2510 NAMEMessage(s) Waiting+++ 2511 CALL: ###DATE04172136...CALLMWI...LINEHOME...NMBRVoicemail... 2512 NAMENo Messages Waiting+++ 2513 2514>>>> Example for UK telcos: 2515>>>> 2516 CALL: ###DATE04221303...CALLMWI...LINEHOME...NMBRVoicemail... 2517 NAME1 Message Waiting+++ 2518 CALL: ###DATE04221619...CALLMWI...LINEHOME...NMBRVoicemail... 2519 NAME5 Messages Waiting+++ 2520 CALL: ###DATE04230839...CALLMWI...LINEHOME...NMBRVoicemail... 2521 NAMENo Messages Waiting+++ 2522 2523>> - <a name="line-type-callinfo"></a><font color="red">CALLINFO:</font> 2524 2525>>> A text line that indicates the telephone lineid and call start/end 2526information. It is sent to the server and converted into an <font 2527color="red">END:</font> text line when a call completes. The text line 2528is comprised of field pairs, the first contains the field name and the 2529second contains the field data. Fields are separated by ..., the first 2530field starts after \#\#\# and the last field ends in +++. The call 2531start/end information is only obtained from gateways that provide such 2532info: 2533 2534>>>> `CALLINFO: ###<end>...DATE<datetime>...SCALL<dt>...ECALL<dt>...CALL<io>... 2535 LINE<lineid>...NMBR<tn>...NAME<name>+++` 2536 2537>>> The <font color="red">CALLINFO:</font> line has the following fields: 2538 2539>>>> 2540 <label><data> | Description 2541 ------------------|:-------------------------------------------------------- 2542 \#\#\# | start of the information part of the message being sent to the server 2543 end | where end is either BYE or CANCEL 2544 ... | field separator 2545 DATEdatetime | where datetime is [mmddhhmm or ddmmhhmm](#gen-datetime), m = month, d = day, h = hour, m = minute 2546 ... | field separator 2547 SCALLdate time | where start of call date is [mm/dd/yyyy](#gen-datetime), a space and time is [hh:mm:ss in 24-hour format](#gen-datetime), m = month, d = day, y = year, h = hour, m = minute, s=second 2548 ... | field separator 2549 ECALLdate time | where end of call date is [mm/dd/yyyy](#gen-datetime), a space and time is [hh:mm:ss in 24-hour format](#gen-datetime), m = month, d = day, y = year, h = hour, m = minute, s=second 2550 ... | field separator 2551 CALLio | where type is either IN or OUT (this is not a pass through of the <font color="red">CALL:</font> CALLtype) 2552 2553<br> 2554 2555>>>> 2556 <label><data> | Description 2557 ------------------|:-------------------------------------------------------- 2558 ... | field separator 2559 LINElineid | where lineid is a [string of characters](#gen-text), NO-LINE or - 2560 ... | field separator 2561 NMBRnumber | where number is a [string of characters](#gen-text), NO-NUMBER or - 2562 ... | field separator 2563 NAMEname | where name is a [string of characters](#gen-text), NO NAME or - 2564 +++ | end of the information part of the message 2565 2566>> - <a name="line-type-goodbye-gw"></a> <font color="red">GOODBYE</font> (new in API 1.6) 2567 (note that there is no trailing colon) 2568 2569>>> The definition of <font color="red">GOODBYE</font> lines for gateways 2570 is the same as for Feature Set 1 clients. Unless otherwise noted, 2571 changes made to <font color="red">GOODBYE</font> lines in API 2572 version 1.6 and higher will apply equally to clients and 2573 gateways. [Click here to go to the Feature Set 1 definition of <font color="red">GOODBYE</font> lines.](#line-type-goodbye-client) 2574 2575>> - <a name="line-type-hello-gw"></a><font color="red">HELLO:</font> (new in API 1.5) 2576 2577>>> The definition of <font color="red">HELLO:</font> lines for gateways is the same as for 2578 Feature Set 1 clients, except that the word 'client' at the beginning of the 2579 <font color="red">HELLO: IDENT: <ident></font> string is replaced with the word 'gateway'. 2580 Unless otherwise noted, changes made to <font color="red">HELLO:</font> lines in API version 1.5 2581 and higher will apply equally to clients and 2582 gateways. [Click here to go to the Feature Set 1 definition of <font color="red">HELLO:</font> lines.](#line-type-hello-client) 2583 2584>> - <a name="line-type-msg-gw-alerts"></a><font color="red">MSG:</font> (gateway alerts) 2585 2586>>> A text line containing a gateway alert that is sent to the 2587 server, saved in the call log and then sent to clients. 2588 It has free-form text only and no field pairs. 2589 2590>>> It has the [{MSGTYPES} Category Structure for Server/Gateway Alerts](#comm-msgtypes-alerts). 2591 2592>>> Example of an ncid2ncid gateway alert: 2593 2594>>>> 2595 MSG: fromhost1 fedora-server:3333 reconnected 2596 2597>> - <a name="line-type-msg-gw-output"></a><font color="red">MSG:</font> (gateway output) 2598 2599>>> A text line containing a gateway message that is sent to the 2600 clients and saved in the call log. 2601 2602>>> It has the [{MSGTYPES} Category Structure for Client/Gateway Output Lines](#comm-msgtypes-client-gw). 2603 2604>> - <a name="line-type-not-gateway"></a><font color="red">NOT:</font> 2605 2606>>> A notification text line of a smartphone message. It is sent to the 2607server and converted into a <font color="red">NOT:</font> text line 2608when a smartphone notification is received. 2609 2610>>> It has the [{MSGTYPES} Category Structure for Client/Gateway Output Lines](#comm-msgtypes-client-gw). 2611 2612<!-- 2613[### FS2: Forwarding Gateway (Server-to-Server) (new in API 1.4)] 2614--> 2615 2616>> ### <a name="fs2-fwdgw"></a> Forwarding Gateway (Server-to-Server) (new in API 1.4) 2617>> 2618 2619>> You might want to implement a Forwarding Gateway in the following scenarios: 2620 2621>> - You have two or more instances of ncidd running to monitor separate modems 2622and you want clients to display call activity from both (or more) modems. 2623Most clients can connect to only one ncidd instance at a time, but by using 2624a Forwarding Gateway you can combine the call activity from several sending 2625servers to a single receiving server. Then, all clients would connect to 2626the single receiving server. 2627 2628>> - You have two or more instances of ncidd running on separate network subnets. 2629 2630>> Distributed with NCID is the ncid2ncid gateway which allows up to four 2631sending servers to be combined and transmitted to a single receiving server. 2632 2633>> There needs to be a method to distinguish which call activity is 2634being forwarded. This method involves prefixing line types with a "+". 2635When ncid2ncid collects call activity from the sending servers, it adds 2636the "+" before transmitting it to the single receiving server. The receiving 2637server (an instance of ncidd) strips the "+" and sends the call activity 2638to all listening clients. 2639 2640>> Here's a hypothetical example: Two Raspberry Pi computers are running 2641ncidd and each have their own modem to monitor. A third computer running 2642Fedora has no access to modems but does have an Apple iPad and an Android 2643tablet connecting as ncid clients. All of these devices are on the same 2644network subnet. 2645 2646>> - RPi #1, IP address 192.168.9.101, port 3333 2647 2648>> - RPi #1, IP address 192.168.9.102, port 3334 2649 2650>> - Fedora, IP address 192.168.9.111, port 3335 2651 2652>> - Apple iPad and Android tablet both configured to connect to the 2653Fedora computer, port 3335. 2654 2655>> This will require ncid2ncid to be configured such that RPi#1 and RPi#2 2656are two sending servers and the Fedora computer is the receiving server. 2657 2658>> 2659>> +-------------------------+ 2660>> | ncid2ncid on Fedora | 2661>> | | 2662>> RPi#1==>|sending server #1 (CID:) | +-----------------+ 2663>> | | | (CID:)|==>Apple iPad 2664>> | receiving server (+CID:)|==>| ncidd on Fedora | 2665>> | | | (CID:)|==>Android tablet 2666>> RPi#2==>|sending server #2 (CID:) | +-----------------+ 2667>> | | 2668>> +-------------------------+ 2669 2670>> 2671 2672<!-- 2673[### FS2: CLIENT IMPLEMENTATION] 2674--> 2675 2676> 2677> ### <a name="fs2-client-impl"></a> CLIENT IMPLEMENTATION 2678 2679>> - implement a Feature Set 1 client 2680 2681>> - (New in API 1.5) send zero or more <font color="red">HELLO:</font> lines at connect 2682 2683>> - if a call log is received, it may also: 2684 2685>>> - contain <font color="red">XXXLOG:</font> text lines where <font color="red">XXX</font> 2686 is one of the <font color="red">{CALLTYPES}</font> or 2687 <font color="red">{MSGTYPES}</font> designated Feature Set 2 in 2688 the [Categories table](#comm-table); these should be parsed and displayed 2689 2690>>> - contain <font color="red">ENDLOG:</font> text lines which can be optionally parsed and displayed 2691 2692>> - receive zero or more <font color="red">OPT: <option></font> lines 2693 2694>> - receive a <font color="red">300 End of server startup</font> message 2695 2696>> - configure options received by <font color="red">OPT:</font> lines 2697 2698>>> (New in API 1.3) Unless otherwise noted, all <font color="red">OPT:</font> lines output by 2699 the server are for informational and troubleshooting purposes 2700 only. Clients can optionally make use of them by giving the user a 2701 way to display them. Otherwise, clients are not required to display 2702 them, do not need to take any action on them and can safely ignore them. 2703 See [Feature Set 1 <font color="red">OPT:</font> definition](#line-type-opt) 2704 and [Feature Set 1: Client Implementation](#fs1-client-impl) for 2705 more information. 2706 2707>> - possibly receive a <font color="red">CIDINFO:</font> at the end of 2708the call 2709 2710>> - possibly receive any of the <font color="red">{CALLTYPES}</font> or <font color="red">{MSGTYPES}</font> designated Feature Set 2 in the [Categories table](#comm-table) 2711 2712>> - possibly receive an <font color="red">END:</font> line whenever a 2713call completes 2714 2715>> - ignore all other lines 2716 2717<!-- 2718[### FS2: Optional Client-to-Module] 2719--> 2720 2721>> ### <a name="fs2-client2module"></a> Optional Client-to-Module 2722 2723>> The optional client module lines are the same as in Feature Set 1, 2724except the call or message type list is expanded and includes the <font color="red">{CALLTYPES}</font> and <font color="red">{MSGTYPES}</font> designated Feature Set 2 in the [Categories table](#comm-table). 2725 2726>> (New in API 1.5) Send zero or more <font color="red">HELLO:</font> 2727 lines at connect. In particular, sending a <font color="red">HELLO: CMD: no_log</font> 2728 line can improve performance because it forces the server not to send 2729 the call log. 2730 2731<!-- 2732[## Feature Set 3: Client Job Support] 2733--> 2734 2735## <a name="fs3-client-job-support"></a> Feature Set 3: Client Job Support 2736 2737> A client can send a "job" to the server to control certain server 2738 features and/or to query/update certain server settings. As an example, 2739 a connected client can trigger the creation of an entry in 2740 **ncidd.alias**, or add a phone number to **ncidd.blacklist**, on-the-fly. 2741 2742> The majority of the Client Jobs sent by a client are completed 2743 immediately by the server and the server sends back the results. No 2744 further interaction between the client and server is needed. 2745 2746> <a name="fs3-server-steps"></a> The exceptions are the 2747 <font color="red">REQ: UPDATE</font> and 2748 <font color="red">REQ: UPDATES</font> Client Jobs (commands). These 2749 work by having the server create temporary copies of the call log(s) 2750 and then applying alias updates to them. The server sends back a 2751 summary to the user of what **will** be changed. The server is then 2752 free to accept the next set of Client Jobs from any connected client. 2753 2754>> NOTE: The server does not support concurrent clients issuing the 2755 <font color="red">REQ: UPDATE</font> and 2756 <font color="red">REQ: UPDATES</font> Client Jobs. 2757 This is not enforced. 2758 2759> The temporary call log(s) remain in a limbo state until the server 2760 receives a <font color="red">WRK: <command></font> line type. 2761 When <command> indicates acceptance, the server removes the 2762 original call log(s) and replaces them with the temporary one(s). 2763 When <command> indicates rejection (cancellation), the server 2764 removes the temporary call log(s). 2765 2766> When you use Client Jobs, you need to keep in mind their effect on 2767 the state of the alias, blacklist and whitelist tables in the 2768 server's memory and the effect on the current call log that may 2769 already be loaded by all connected clients. 2770 2771> - Updates to the alias, blacklist and whitelist files execute the 2772 external **ncidutil** tool via the 2773 <font color="red">REQ: <alias|black|white></font> 2774 commands. The client that performs these changes should 2775 follow up with a <font color="red">REQ: RELOAD</font> request to 2776 update the server's tables in memory. Such changes are then 2777 immediately available to all connected clients as call activity 2778 continues. You can batch the updates by sending several changes 2779 in a row, followed by a single 2780 <font color="red">REQ: RELOAD</font> request. 2781 2782> - Updates to call log(s) execute the external **cidupdate** tool via 2783 <font color="red">REQ: UPDATE | UPDATES</font> commands. 2784 The client that performs these changes should follow up with a 2785 <font color="red">REQ: REREAD</font> request to have the modified 2786 current call log resent to the client. You can batch the updates 2787 by sending several changes in a row, followed by a single 2788 <font color="red">REQ: REREAD</font> request. Only the client that 2789 requests the <font color="red">REQ: REREAD</font> will be updated; 2790 all other connected clients will either need to be manually 2791 restarted, or manually execute a <font color="red">REQ: REREAD</font> 2792 request. 2793> 2794 2795<!-- 2796[### FS3: OVERVIEW OF AVAILABLE CLIENT JOBS] 2797--> 2798 2799> ### <a name="fs3-overview"></a> OVERVIEW OF AVAILABLE CLIENT JOBS 2800 2801>> Client Jobs are initiated when clients send <font color="red">REQ:</font> 2802 line types to the server. The general format is: 2803 2804>>> <font color="red">REQ:</font> <command> [<arguments>] 2805>> 2806 2807>> When an already-initiated Client Job requires additional information 2808 from the user, the client will send <font color="red">WRK:</font> 2809 line types to the server. The general format is: 2810 2811>>> <font color="red">WRK:</font> <command> <arguments> 2812>> 2813 2814>> Commands and arguments are case sensitive. 2815 2816>> See the table at the beginning of [Client Job Examples](#fs3-examples) 2817 for brief descriptions of each <font color="red">REQ:</font> and 2818 <font color="red">WRK:</font> command. 2819 2820>> At a minimum, the Client Jobs needed to query and add an alias are as 2821follows. Blacklist/whitelist queries and updates are similar. 2822 2823 2824>> Step | Job Request | What it does 2825>> ---- | --------------------------------------| ------------ 2826>> 1 | <font color="red">REQ: INFO</font> <number>&&<name> | Check to see if an entry exists in alias/blacklist/whitelist 2827>> 2 | <font color="red">REQ: alias</font> <add> <arguments> | Write a new entry to **ncidd.alias** 2828>> 3 | <font color="red">REQ: RELOAD</font> | Force the NCID server to reload the modified alias list 2829>> 4 | <font color="red">REQ: UPDATE</font> | <font color="red">UPDATES</font> | Allow the user to preview the update to the call log(s) 2830>> 5 | <font color="red">WRK: ACCEPT LOG</font> | <font color="red">LOGS</font> | User commits the update(s) 2831>> 6 | <font color="red">REQ: REREAD</font> | Force the server to resend the updated current call log to the client performing the update 2832> 2833<!-- 2834[### FS3: SERVER IMPLEMENTATION] 2835--> 2836> 2837> ### <a name="fs3-server-impl"></a> SERVER IMPLEMENTATION 2838 2839>> - when a client establishes a connection to the server, send a list 2840 of server-supported Client Job options to client, one 2841 <font color="red">OPT: <option></font> line for each option, 2842 just before sending <font color="red">300 End of server startup</font> 2843 message 2844 2845>> - process user-initiated Client Jobs in response to client 2846 <font color="red">REQ:</font> and <font color="red">WRK:</font> 2847 requests 2848 2849<!-- 2850[### FS3: Server Output Lines] 2851--> 2852 2853>> ### <a name="fs3-server-output"></a> Server Output Lines 2854 2855>> The general structure of Server Output Lines consists of three line 2856 types: a start-of-server-data line, one or more lines of the server data, then an 2857 end-of-server-data line. 2858 2859>> Each start-of-server-data line is paired with a specific 2860 end-of-server-data line as indicated below. For clarity, lines are 2861 indented to show their logical structure. 2862<br><br> 2863 2864>> - `400 Start of data requiring OK` 2865>> `INFO: <data returned for the request>` 2866>> `INFO: <data returned for the request>` 2867>> `...` 2868>> `410 End of data` 2869<br><br> 2870 2871>> - `401 Start of data requiring ACCEPT or REJECT` 2872>> `INFO: <data returned for the request>` 2873>> `INFO: <data returned for the request>` 2874>> `...` 2875>> `410 End of data` 2876<br><br> 2877 2878>> - `402 Start of data showing status of handled request` 2879>> `RESP: <a server output line>` 2880>> `RESP: <a server output line>` 2881>> `...` 2882>> `411 End of response` 2883<br><br> 2884 2885>> - `403 Start of data defining permitted requests` 2886>> `INFO: <data returned for the request>` 2887>> `INFO: <data returned for the request>` 2888>> `...` 2889>> `411 End of response` 2890<br><br> 2891 2892>> The contents of the <font color="red">INFO:</font> and 2893 <font color="red">RESP:</font> lines depend entirely on the Client Job 2894 being processed. 2895 2896>> <a name="fs3-server-reread"></a> For example, if a client sends a <font color="red">REQ: REREAD</font> 2897 request ("resend call log"), the server will output line types 2898 <font color="red">250</font> - 2899 <font color="red">253</font>, 2900 <font color="red">OPT:</font> and 2901 <font color="red">300</font> exactly as specified 2902 in [Feature Set 1: Modem and Device Support](#fs1-modem-support-send-log). 2903 Their definitions are not included below. 2904 2905>> The rest of this section contains the definitions of each server output 2906 line type for Client Jobs. 2907 2908>> - <a name="line-type-400"></a><font color="red">400</font> 2909 2910>>> Start of data that the client should present to the user for 2911 acknowledgment. The data is in the form of one or more 2912 <font color="red">INFO:</font> lines and ends with 2913 <font color="red">410</font>. 2914 2915>>> <font color="dimgray">(Added in API 1.2) Nothing is sent back to the 2916 server.</font> 2917 2918 2919>>>> `400 Start of data requiring an OK` 2920 2921>> - <a name="line-type-401"></a><font color="red">401</font> 2922 2923>>> Start of data that requires <font color="red">ACCEPT</font> or <font 2924 color="red">REJECT</font> from client (a client should follow up with an 2925 appropriate <font color="red">WRK:</font> response). The data is in the form 2926 of one or more <font color="red">INFO:</font> lines and ends with 2927 <font color="red">410</font>. 2928 2929 2930>>>> `401 Start of data requiring ACCEPT or REJECT` 2931 2932>> - <a name="line-type-402"></a><font color="red">402</font> 2933 2934>>> Start of data showing the server results of a Client Job. The data 2935 is in the form of one or more <font color="red">RESP:</font> lines 2936 and ends with <font color="red">411</font>. 2937 2938>>>> `402 Start of data showing status of handled request` 2939 2940>> - <a name="line-type-403"></a><font color="red">403</font> 2941 2942>>> When a Client Job is submitted, the server will validate the 2943 request and send back one or more 2944 <font color="red">INFO:</font> lines to indicate 2945 what actions the client can do next, followed by an 2946 ending <font color="red">411</font> line. 2947 2948>>> For example, a Client Job can request the status 2949 of a phone number and as part of the server response 2950 there will be an indication as to whether the phone number 2951 is present or not in the blacklist. This tells the client making 2952 the request whether it can give the user the option to 2953 remove it from, or add it to, the blacklist. 2954 2955>>>> `403 Start of data defining permitted requests` 2956 2957>> - <a name="line-type-410"></a><font color="red">410</font> 2958 2959>>> End of data returned from server. Used to end 2960 <font color="red">400</font> and <font color="red">401</font> 2961 server messages: 2962 2963 2964>>>> `410 End of data` 2965 2966>> - <a name="line-type-411"></a><font color="red">411</font> 2967 2968>>> End of response. Used to end <font color="red">402</font> 2969 and <font color="red">403</font> server messages: 2970 2971>>>> `411 End of response` 2972 2973>> - <a name="line-type-info"></a><font color="red">INFO:</font> 2974 2975>>> The server will send an appropriate beginning 2976 <font color="red">40x</font> line, then one or 2977 more <font color="red">INFO:</font> lines and 2978 finally an ending <font color="red">41x</font> 2979 line. 2980 2981>>> The server outputs <font color="red">INFO:</font> lines 2982 in one of two formats: 2983 2984>>> - Format 1: Free form text, with as many <font color="red">INFO:</font> lines as needed. 2985 2986>>>> It will have a beginning <font color="red">401</font> 2987 line, then the <font color="red">INFO:</font> lines and 2988 finally an ending <font color="red">410</font> 2989 line. 2990 2991>>> - Format 2: A specific structure unique to <font color="red">REQ: INFO</font> requests. 2992 2993>>>> It will have a beginning <font color="red">403</font> 2994 line, then the <font color="red">INFO:</font> lines and 2995 finally an ending <font color="red">411</font> 2996 line. 2997 2998>> - <a name="line-type-resp"></a><font color="red">RESP:</font> 2999 3000>>> The server will send a <font color="red">402</font> line, then one or 3001 more <font color="red">RESP:</font> lines and finally an ending 3002 <font color="red">411</font> line. 3003 3004>>> The server sends one <font color="red">RESP:</font> line for each 3005 line of server output. 3006 3007>>> RESP: <a server output line> 3008 3009>> - <a name="line-type-rply"></a><font color="red">RPLY: dial - <status></font> 3010 3011>>> Send the client the status of a <font color="red">REQ: DIAL|DIAL_ABORT</font> 3012 Client Job, where <status> can be one of: 3013 3014>>> hungup <number> on line "<lineid>" 3015>>> 3016>>> dial failed, modem returned <error text from modem> 3017>>> 3018>>> format error: <error text from modem> 3019 3020>>> A <font color="red">RPLY:</font> line normally follows the server 3021 <font color="red">411</font> response to 3022 <font color="red">REQ: DIAL|DIAL_ABORT</font>. However, this is not 3023 guaranteed and a client should expect <font color="red">RPLY:</font> 3024 at any time. 3025 3026> 3027<!-- 3028[### FS3: CLIENT IMPLEMENTATION] 3029--> 3030> 3031> ### <a name="fs3-client-impl"></a> CLIENT IMPLEMENTATION 3032 3033>> If you want to implement a client to take advantage of Client Jobs: 3034 3035>> - you will likely want to design a GUI as Client Jobs 3036 are intended to interact with a user 3037 3038>> - client must process server options (<font color="red">OPT:</font> 3039 lines) which are provided just before a 3040 <font color="red">300 End of server startup</font> line 3041 3042>>> (New in API 1.3) Unless otherwise noted, all <font color="red">OPT:</font> lines output by 3043 the server are for informational and troubleshooting purposes 3044 only. Clients can optionally make use of them by giving the user a 3045 way to display them. Otherwise, clients are not required to display 3046 them, do not need to take any action on them and can safely ignore them. 3047 See [Feature Set 1 <font color="red">OPT:</font> definition](#line-type-opt) 3048 and [Feature Set 1: Client Implementation](#fs1-client-impl) for 3049 more information. 3050 3051>> A graphical NCID client will typically have the following features: 3052 3053>> - A window displaying contents of the current call log (a.k.a. call 3054 history). When the user selects a displayed line, the client will 3055 initiate a <font color="red">REQ: INFO alias</font> request to find 3056 out what actions are permitted for the caller phone number and name 3057 on that line (e.g., if there is no alias give an option to add a new 3058 one, if the number is on the blacklist/whitelist give an option to 3059 remove it, etc.). 3060 3061>> - Provide a way for the user to manually force the server to 3062 reload the server's alias, blacklist and whitelist files via a 3063 <font color="red">REQ: RELOAD</font> request. 3064 3065>>> - <font color="dimgray">(Removed in API 1.3) <strike>only if the 3066 server sends <font color="red">OPT: hangup</font> will the user have 3067 an option to force the server to reload the blacklist/whitelist files 3068 </strike></font> 3069 3070>> - Provide a way for the user to manually force the server to 3071 update the current call log or all call logs with aliases via the 3072 <font color="red">REQ: UPDATE | UPDATES</font> request. 3073 3074>> - Provide a way for the user to manually force the server to 3075 resend the current call log to the client via the 3076 <font color="red">REQ: REREAD</font> request. 3077 3078>> - (New in API 1.6) When the user selects a displayed line, provide a way 3079 to dial a number, or abort a dial in progress. 3080 3081>> - (New in API 1.6) Monitor the server for <font color="red">RPLY:</font> 3082 lines. These give the success/fail result of dialing a number. Display 3083 to the user as appropriate. 3084 3085<!-- 3086[### FS3: Client-to-Server] 3087--> 3088 3089>> 3090>> ### <a name="fs3-client2server"></a> Client-to-Server 3091 3092>> Client Jobs are initiated when clients send <font color="red">REQ:</font> 3093 line types to the server. The general format is: 3094 3095>>> - <a name="line-type-req"></a><font color="red">REQ:</font> <command> [<arguments>] 3096>> 3097>> where <command> is one of the following: 3098 3099>>> alias | black | white | DIAL | DIAL_ABORT | INFO | RELOAD | REREAD | UPDATE | UPDATES 3100 3101>>> - (New in API 1.6) The <font color="red">DIAL</font> and <font color="red">DIAL_ABORT</font> commands were added to 3102 the above list. 3103 3104>> When an already-initiated Client Job requires additional information 3105 from the user, the client will send <font color="red">WRK:</font> 3106 line types to the server. The general format is: 3107 3108>>> - <a name="line-type-wrk"></a><font color="red">WRK:</font> <command> <arguments> 3109>> 3110>> where <command> <arguments> is one of the following: 3111 3112>>> ACCEPT LOG | ACCEPT LOGS | REJECT LOG | REJECT LOGS 3113 3114 3115>> Commands and arguments are case sensitive. 3116 3117>> The following Client Jobs are supported. 3118 3119>> - <a name="line-type-req-alias"></a><font color="red">REQ: alias add</font> "<number>&&<alias>" "<type>&&<name>" 3120 3121>>> Add to alias list. A client would typically offer the user the 3122 option to add an item to the alias list if the 3123 <font color="red">INFO: alias</font> line returned NOALIAS. 3124 3125>>> where: 3126 3127>>> - number is from the call log 3128 3129>>> - alias is input from the user 3130 3131>>> - type is the alias type or NOALIAS if none 3132 3133>>> - name is from the call log 3134 3135>> - <font color="red">REQ: alias modify</font> "<number>&&<alias>" "<type>&&<name>" 3136 3137>>> Modify alias. A client would typically offer the user the option to 3138 modify an alias if the <font color="red">INFO: alias</font> line did 3139 not return NOALIAS. 3140 3141>>> where: 3142 3143>>> - number is from the call log 3144 3145>>> - alias is new alias 3146 3147>>> - type is the alias type or NOALIAS if none 3148 3149>>> - name is from the call log 3150 3151>>> Modifying an alias and specifying a new alias of nothing (null) is 3152 the same as removing an existing alias. 3153 3154>> - <font color="red">REQ: alias remove</font> "<number>&&" "<type>&&<name>" 3155 3156>>> Remove alias. A client would typically offer the user the option to 3157 modify an alias if the <font color="red">INFO: alias</font> line did 3158 not return NOALIAS. 3159 3160>>> where: 3161 3162>>> - number is from the call log 3163 3164>>> - type is the alias type or NOALIAS if none 3165 3166>>> - name is from the call log 3167 3168>> - <a name="line-type-req-black"></a><font color="red">REQ: black add</font> "<item>" "<comment>" 3169 3170>>> Add an item to the blacklist. Item is the name or number from the 3171 call log file. A client would typically offer the user the option to 3172 add an item to the black list if the <font color="red">INFO:</font> 3173 response line was <font color="red">INFO: neither</font>. 3174 3175>>>> <font color="dimgray">(Removed in API 1.1) <strike> The server must have 3176 sent and the client must have received, 3177 <font color="red">OPT: hangup</font> to enable this Client Job.</strike></font> 3178 3179>> - <font color="red">REQ: black remove </font>"<item>" "" 3180 3181>>> Remove from black list. Item is the name or number from the call 3182 log file. A client would typically offer the user the option to 3183 remove an item from the black list if the 3184 <font color="red">INFO:</font> response was either 3185 <font color="red">INFO: black name</font> or 3186 <font color="red">INFO: black number</font>. 3187 3188>>>> <font color="dimgray">(Removed in API 1.1) <strike> The server must have 3189 sent and the client must have received, 3190 <font color="red">OPT: hangup</font> to enable this Client Job.</strike></font> 3191 3192 3193>> - <a name="line-type-req-white"></a><font color="red">REQ: white add</font> "<item>" "<comment>" 3194 3195>>> Add to white list. Item is the name or number from the call log 3196 file. A client would typically offer the user the option to add an 3197 item to the white list if the <font color="red">INFO:</font> response 3198 line was <font color="red">INFO: neither</font>. 3199 3200>>>> <font color="dimgray">(Removed in API 1.1) <strike> The server must have 3201 sent and the client must have received, 3202 <font color="red">OPT: hangup</font> to enable this Client Job.</strike></font> 3203 3204 3205>> - <font color="red">REQ: white remove</font> "<item>" "" 3206 3207>>> Remove from white list. Item is the name or number from the call 3208 log file. A client would typically offer the user the option to 3209 remove an item from the white list if the 3210 <font color="red">INFO:</font> response line was either 3211 <font color="red">INFO: white name</font> or 3212 <font color="red">INFO: white number</font>. 3213 3214>>>> <font color="dimgray">(Removed in API 1.1) <strike> The server must have 3215 sent and the client must have received, 3216 <font color="red">OPT: hangup</font> to enable this Client Job.</strike></font> 3217 3218>> - <a name="line-type-req-dial"></a><font color="red">REQ: <DIAL|DIAL_ABORT></font> <number>&&<name>&&<lineid> (new in API 1.6) 3219 3220>>> Use a modem locally connected to the server to dial <number>. 3221 <name> is provided for display purposes only. 3222 3223>>> When the server has more than one modem configured for dialing out, 3224 <lineid> specifies which modem, e.g., POTS, HOME, etc. Multiple 3225 modem support is currently incomplete; <lineid> should be 3226 considered a placeholder for now because only one modem is supported. 3227 3228>>> The number, name and lineid are separated by <font color="red">&&</font>. 3229 3230>>> No check is made to see if <number> is blacklisted; blacklisted 3231 numbers can be dialed. 3232 3233>>> Use the <font color="red">REQ: DIAL_ABORT</font> line to cancel a dial in progress. 3234 3235>>> Once the server has issued the ATDT command, it must start a dial delay 3236 timer (a minimum of 5 seconds is suggested) and proceed with its normal 3237 polling process to check for client/gateway connections and data, 3238 including a possible <font color="red">REQ: DIAL_ABORT</font> Client 3239 Job. While the dial delay timer counts down, the server must monitor 3240 and react to the status of the modem. 3241 3242>>> If the timer reaches zero without detecting a problem, the dial is 3243 considered successful and assumes the user has picked up the line. 3244 The server then sends a modem ATH0 command sequence to disconnect from 3245 the phone line; as long as the user is still talking to the dialed party, 3246 the call itself will not be terminated. 3247 3248>>> When the dial's success, user abort, or failure is determined, the server 3249 will send the dial status using the <font color="red">RPLY:</font> 3250 line type. It gets sent to the client that initiated the dial. 3251 3252>>> The server will generate an <font color="red">OUT:</font> line if the number 3253 is successfully dialed. 3254 3255>>> A special case exists where other devices can detect outgoing calls. 3256 In order to avoid creating a duplicate <font color="red">OUT:</font> 3257 line, a server needs to check all 3258 <font color="red">HELLO: IDENT: <ident></font> lines for the presence 3259 of the uppercase text *[OUT]* following the version. When found, a flag is set 3260 to prevent the server from generating the <font color="red">OUT:</font> line. 3261 3262>>> For example, the sip2ncid gateway can detect outgoing calls. It depends 3263 on the SIP implementation of the Telco or VoIP provider. 3264 When sip2ncid connects to the server, the <ident></font> string 3265 will have *[OUT]*, so set a flag. If <font color="red">REQ: DIAL</font> 3266 is successful, it is assumed that sip2ncid will have generated the 3267 <font color="red">OUT:</font> as part of its normal processing. 3268 3269>> - <a name="line-type-req-info"></a><font color="red">REQ: INFO</font> <number>&&<name> <br> <font color="red">REQ: INFO</font> <number>&&<name>&&<lineid> 3270 3271>>> Request the status of alias, blacklist and whitelist for a given 3272 number, name and optional lineid. 3273 3274>>> (New in API 1.6) Also requests the status of whether the number can 3275 be dialed. 3276 3277>>> The number, name and optional lineid are separated by <font color="red">&&</font>. 3278 3279>>> To retrieve the alias status for number and name, there must be an 3280 exact match on both. 3281 3282>>> To retrieve the alias status for the optional lineid, there must be 3283 an exact match on the lineid. 3284 3285>>> To retrieve whitelist and blacklist status, either number, name, or 3286 both number and name can match the blacklist or whitelist entry 3287 (i.e. both number and name do not have to match, but one of them must 3288 match). 3289 3290>>> The server responds with three <font color="red">INFO:</font> lines 3291 that have the following general format: 3292 3293>>>> - First <font color="red">INFO:</font> line contains alias status: 3294 3295>>>>>> `INFO: alias <number/name type> [<lineid type>]` 3296 3297>>>>> where <number/name type> can be one of: 3298 3299>>>>>> NOALIAS | NMBRONLY | NAMEONLY | NMBRNAME | NMBRDEP | NAMEDEP 3300 3301>>>>> and the optional <lineid type> can be one of: 3302 3303>>>>>> NOALIAS | LINEONLY 3304 3305>>>> - Second <font color="red">INFO:</font> line 3306 contains blacklist and whitelist status: 3307 3308>>>>>> `INFO: <status>` 3309 3310>>>>> where <status> can be one of: 3311 3312>>>>>> neither | 3313>>>>>> black name | white name | 3314>>>>>> black number | white number 3315 3316>>>> - (New in API 1.6) Third <font color="red">INFO:</font> line 3317 indicates whether the server has been enabled to dial the number 3318 using a locally attached modem: 3319 3320>>>>>> `INFO: dial <status>` 3321 3322>>>>> where <status> can be one of: 3323 3324>>>>>> NODIAL | 3325>>>>>> <number>&&<name> 3326 3327>> - <a name="line-type-req-reload"></a><font color="red">REQ: RELOAD</font> 3328 3329>>> Reload alias, blacklist and whitelist files. 3330 3331>>> <font color="dimgray">(Removed in API 1.3) <strike> (the blacklist and 3332 whitelist files will not be reloaded unless the server 3333 <font color="red">OPT: hangup</font> option is received)</strike></font> 3334 3335>> - <a name="line-type-req-reread"></a><font color="red">REQ: REREAD</font> 3336 3337>>> Request that the server resend the call log. It is only sent to the 3338 client issuing <font color="red">REQ: REREAD</font>. The server 3339 responds with line types <font color="red">250</font> - 3340 <font color="red">253</font>, <font color="red">OPT:</font> 3341 and <font color="red">300</font> exactly as specified 3342 in [Feature Set 1: Modem and Device Support](#fs1-modem-support-send-log). 3343 3344>> - <a name="line-type-update"></a><font color="red">REQ: UPDATE</font> 3345 3346>>> Make a temporary copy of the ***current*** call log to process any 3347 alias changes. This executes the external **cidupdate** tool. See 3348 also [Note 1](#fs3-limbo) and [Note 2](#fs3-keep-stamp) below. 3349 3350>> - <a name="line-type-updates"></a><font color="red">REQ: UPDATES</font> 3351 3352>>> Make temporary copies of ***all*** call logs to process any alias 3353 changes. This executes the external **cidupdate** tool. See 3354 also [Note 1](#fs3-limbo) and [Note 2](#fs3-keep-stamp) below. 3355 3356>> - <a name="line-type-wrk-accept-log"></a><font color="red">WRK: ACCEPT LOG</font> 3357 3358>>> The user has indicated that changes to the ***current*** call log by 3359 <font color="red">REQ: UPDATE</font> have been accepted. This causes 3360 the original call log to be removed and replaced with the temporary 3361 call log. See also [Note 1](#fs3-limbo) and [Note 2](#fs3-keep-stamp) 3362 below. 3363 3364>> - <a name="line-type-wrk-reject-log"></a><font color="red">WRK: REJECT LOG</font> 3365 3366>>> The user has indicated that changes to the ***current*** call log by 3367 <font color="red">REQ: UPDATE</font> have been rejected. This causes 3368 the temporary call log to be removed and no permanent updates take 3369 place. See also [Note 1](#fs3-limbo) below. 3370 3371>> - <a name="line-type-wrk-accept-logs"></a><font color="red">WRK: ACCEPT LOGS</font> 3372 3373>>> The user has indicated that changes to ***all*** call logs by 3374 <font color="red">REQ: UPDATES</font> have been accepted. This causes 3375 the original call logs to be removed and replaced with the temporary 3376 call logs. See also [Note 1](#fs3-limbo) and [Note 2](#fs3-keep-stamp) 3377 below. 3378 3379>> - <a name="line-type-wrk-reject-logs"></a><font color="red">WRK: REJECT LOGS</font> 3380 3381>>> The user has indicated that changes to ***all*** call logs by 3382 <font color="red">REQ: UPDATES</font> have been rejected. This causes 3383 the temporary call logs to be removed and no permanent updates take 3384 place. See also [Note 1](#fs3-limbo) below. 3385 3386> <a name="fs3-limbo"></a> Note 1: Clients are responsible for keeping 3387 track of pending call log updates initiated by 3388 <font color="red">REQ: UPDATE | UPDATES</font>. The temporary call 3389 logs will remain on the server indefinitely until a client sends a 3390 <font color="red">WRK:</font> command. 3391 3392> <a name="fs3-keep-stamp"></a> Note 2: The **cidupdate** tool preserves 3393 the date/time stamp of the original call log(s) when replacing them 3394 with the temporary log(s). 3395 3396<!-- 3397[### FS3: REQUIREMENTS FOR DIAL-A-NUMBER CLIENT JOB] 3398--> 3399 3400> ### <a name="fs3-dial-req"></a> REQUIREMENTS FOR DIAL-A-NUMBER CLIENT JOB (new in API 1.6) 3401 3402<!-- 3403[### FS3: lineid] 3404--> 3405 3406> ### <a name="fs3-dial-lineid"></a> *lineid* 3407 3408>> The lineid is *not* the operating system device name, i.e., it is not 3409 /dev/ttyACM0 or COM1: or similar. 3410 3411>> Click on the links to be taken to the complete definition: 3412 3413>>- The [<font color="red">REQ: DIAL</font>](#line-type-req-dial) Client 3414 Job uses lineid to allow the user to select which modem will be used 3415 to dial the number. 3416 3417>>- The [<font color="red">REQ: INFO</font>](#line-type-req-info) Client 3418 Job uses the optional lineid only to check whether there is an alias 3419 for lineid. The associated <font color="red">INFO: dial</font> 3420 server response *does not* return a lineid on purpose because the 3421 user, not the server, chooses the lineid for dialing. 3422 3423<!-- 3424[### FS3: Server Implementation] 3425--> 3426 3427> ### <a name="fs3-dial-server-impl"></a> Server Implementation 3428 3429>> The server considers the dial-a-number feature to be enabled if all of the 3430>> following are true: 3431 3432>> - **ncidd.conf::cidinput** indicates an "AT" modem is attached 3433>> - the modem was successfully initialized when ncidd was started 3434>> - the <font color="red">REQ: INFO</font> number to be dialed consists 3435 of only digits 3436 3437>> If the above conditions are not met, the server will respond to the 3438 <font color="red">REQ: INFO</font> Client Job with the following third 3439 <font color="red">INFO:</font> line: 3440 3441>>> `INFO: dial NODIAL` 3442 3443>> The server does not modify the number to be dialed. It is passed as-is 3444 to the modem and dialed using a normal modem ATDT command sequence. 3445 3446>> The server does not care if a number is blacklisted or not. A blacklisted 3447 number can be dialed like any other number. 3448 3449<!-- 3450[### FS3: Client Implementation] 3451--> 3452 3453> ### <a name="fs3-dial-client-impl"></a> Client Implementation 3454 3455>> The client usually interacts with the user by presenting the current 3456 call history and allowing a line to be selected. No validation of the 3457 selected line type (<font color="red">CID:</font>, <font color="red">HUP:</font>, 3458 <font color="red">NOT:</font>, etc.) should be needed because it is 3459 the NMBR field pair that ultimately determines the number to dial. 3460 3461>> It is the responsibility of the client initiating this Client Job to 3462 make sure it sends the proper leading digits to handle long distance 3463 calls, send country codes, access outside lines, etc. 3464 3465<!-- 3466# https://en.wikipedia.org/wiki/555_(telephone_number)#Fictional_usage 3467# https://www.w3schools.com/tags/ref_urlencode.asp 3468--> 3469 3470>> The client can optionally validate the number somewhat: number of 3471 digits, not all zeros, proper area code, 3472 no [555-01XX fictional numbers](https://en.wikipedia.org/wiki/555%5F%28telephone%5Fnumber%29%23Fictional%5Fusage), etc. 3473 This validation is optional because it needs to be country specific. 3474 3475>> If the client's number validation fails, the <font color="red">REQ: DIAL</font> 3476 Client Job should not be sent to the server. 3477 3478<!-- 3479[### FS3: CLIENT JOB EXAMPLES 3480--> 3481 3482> ### <a name="fs3-examples"></a> CLIENT JOB EXAMPLES 3483 3484>> Clicking on the Job Request will show examples of the Client/Server 3485 exchanges. 3486 3487>> Clicking on the <u>(client)</u> link in the table 3488 below will take you to more detailed information and is usually the 3489 place you want to start. Clicking on the <u>(server)</u> link takes you to 3490 an appropriate Server Output section. 3491 3492 3493>> 3494>> Job Request | Description 3495>> ----------------|-------------- 3496>> [<font color="red">REQ: alias</font> <add|modify|remove>](#fs3-example-abw-manip-a) | [(client)](#line-type-req-alias) [(server <font color="red">402</font>)](#line-type-402) Manipulate entries in alias file 3497>> [<font color="red">REQ: black</font> <add|remove>](#fs3-example-abw-manip-b) | [(client)](#line-type-req-black) [(server <font color="red">402</font>)](#line-type-402) Manipulate entries in blacklist file 3498>> [<font color="red">REQ: white</font> <add|remove>](#fs3-example-abw-manip-w) | [(client)](#line-type-req-white) [(server <font color="red">402</font>)](#line-type-402) Manipulate entries in whitelist file 3499>> [<font color="red">REQ: DIAL</font> <number>&&<name>&&<lineid><br><font color="red">REQ: DIAL_ABORT</font> <number>&&<name>&&<lineid>](#fs3-example-dial) | [(client)](#line-type-req-dial) [(server <font color="red">402</font>)](#line-type-402) Dial a number (new in API 1.6) 3500>> [<font color="red">REQ: INFO</font> <number>&&<name> <br><font color="red">REQ: INFO</font> <number>&&<name>&&<lineid>](#fs3-example-abw-query) | [(client)](#line-type-req-info) [(server <font color="red">403</font>)](#line-type-403) Query alias, blacklist and whitelist status for a given number, name and/or lineid 3501>> [<font color="red">REQ: RELOAD</font>](#fs3-example-abw-reload) | [(client)](#line-type-req-reload) [(server <font color="red">400</font>)](#line-type-400) Force the NCID server to reload alias, blacklist and whitelist tables into the server's memory 3502>> [<font color="red">REQ: REREAD</font>](#fs3-example-reread) | [(client)](#line-type-req-reread) [(server)](#fs3-server-reread) Force the NCID server to resend the ***current*** call log to the client 3503>> [<font color="red">REQ: UPDATE</font>](#fs3-example-update) | [(client)](#line-type-update) [(server <font color="red">401</font>)](#line-type-401) Temporarily update the ***current*** call log to process any alias changes. Changes are made permanent only if client responds with <font color="red">WRK: ACCEPT LOG</font>. 3504>> [<font color="red">REQ: UPDATES</font>](#fs3-example-updates) | [(client)](#line-type-updates) [(server <font color="red">401</font>)](#line-type-401) Temporarily update ***all*** call logs to process any alias changes. Changes are made permanent only if client responds with <font color="red">WRK: ACCEPT LOGS</font>. 3505>> [<font color="red">WRK: ACCEPT LOG</font>](#fs3-example-wrk-log-accept) | [(client)](#line-type-wrk-accept-log) [(server)](#fs3-server-steps) Accept and make permanent the server's temporary updates to the ***current*** call log 3506>> [<font color="red">WRK: REJECT LOG</font>](#fs3-example-wrk-log-reject) | [(client)](#line-type-wrk-reject-log) [(server)](#fs3-server-steps) Reject (cancel) the server's temporary updates to the ***current*** call log 3507 3508<br> 3509<br> 3510 3511>> 3512>> Job Request | Description 3513>> ----------------|-------------- 3514>> </>               [<font color="red">WRK: ACCEPT LOGS</font>](#fs3-example-wrk-logs-accept) | [(client)](#line-type-wrk-accept-logs) [(server)](#fs3-server-steps) Accept and make permanent the server's temporary updates to ***all*** call logs 3515>> [<font color="red">WRK: REJECT LOGS</font>](#fs3-example-wrk-logs-reject) | [(client)](#line-type-wrk-reject-logs) [(server)](#fs3-server-steps) Reject (cancel) the server's temporary updates to ***all*** call logs 3516 3517>> Below are examples of the Client/Server exchanges for Job Requests. 3518 3519>> <font color="red">REQ:</font> and <font color="red">WRK:</font> lines 3520 are generated by the client. For readability, server responses are 3521 indented and long lines split using the "\" continuation character. For 3522 brevity, the full paths to **ncidutil**, **cidupdate**, **ncidd.alias**, 3523 **ncidd.blacklist**, **ncidd.whitelist** and **ncidd.conf::cidlog** have been 3524 removed. 3525 3526>> The majority of the alias examples use the NAMEDEP type ("change the 3527 name depending on the phone number") since it is most widely used. 3528 3529>> 3530>> - <a name="fs3-example-abw-manip-a"></a><font color="red">REQ: alias</font> <add|modify|remove> "<number>&&<alias>" "<type>&&<name>" 3531>> 3532 3533>>> - First check to see if there is already an alias on file.... 3534>>> 3535 3536>>>> REQ: INFO 4075551212&&WIRELESS 3537>>>> 3538>>>> 403 Start of data defining permitted requests 3539>>>> INFO: alias NOALIAS 3540>>>> INFO: neither 3541>>>> INFO: dial 4075551212&&WIRELESS 3542>>>> 411 End of response 3543>>> 3544>>> - We got `alias NOALIAS` so add it.... 3545>>> 3546>>>> REQ: alias add "4075551212&&John on Cell" "NAMEDEP&&WIRELESS" 3547>>>> 3548>>>> ncidutil --ignore1 \ 3549>>>> --multi "ncidd.blacklist ncidd.whitelist" \ 3550>>>> "ncidd.alias" Alias add \ 3551>>>> "4075551212&&John on Cell" \ 3552>>>> "NAMEDEP&&WIRELESS" 2>&1 3553>>>> 402 Start of data showing status of handled request 3554>>>> RESP: Modified: ncidd.alias 3555>>>> RESP: added: alias NAME * = "John on Cell" if 4075551212 3556>>>> RESP: Done. 3557>>>> 411 End of response 3558>>> 3559>>> - Modify it.... 3560>>> 3561>>>> REQ: alias modify "4075551212&&John's iPhone" "NAMEDEP&&John on Cell" 3562>>>> 3563>>>> ncidutil --ignore1 \ 3564>>>> --multi "ncidd.blacklist ncidd.whitelist" \ 3565>>>> "ncidd.alias" Alias modify \ 3566>>>> "4075551212&&John's iPhone" \ 3567>>>> "NAMEDEP&&John on Cell" 2>&1 3568>>>> 402 Start of data showing status of handled request 3569>>>> RESP: Modified: ncidd.alias 3570>>>> RESP: from: alias NAME * = "John on Cell" if "4075551212" 3571>>>> RESP: to: alias NAME * = "John's iPhone" if 3572>>>> "4075551212" 3573>>>> RESP: Done. 3574>>>> 411 End of response 3575>>> 3576>>> - Remove it.... 3577>>> 3578>>>> REQ: alias remove "4075551212&&" "NAMEDEP&&John's iPhone" 3579>>>> 3580>>>> ncidutil --ignore1 \ 3581>>>> --multi "ncidd.blacklist ncidd.whitelist" \ 3582>>>> "ncidd.alias" Alias remove \ 3583>>>> "4075551212&&" "NAMEDEP&&John's iPhone" 2>&1 3584>>>> 402 Start of data showing status of handled request 3585>>>> RESP: Modified: ncidd.alias 3586>>>> RESP: removed: alias NAME * = "John's iPhone" if 3587>>>> "4075551212" 3588>>>> RESP: Done. 3589>>>> 411 End of response 3590 3591>>>> Note that the following are equivalent and are treated as "alias remove" 3592>>>> because the new "...&&<alias>" is null. 3593>>>>> REQ: alias modify "4075551212&&" "NAMEDEP&&John's iPhone" 3594>>>>> REQ: alias remove "4075551212&&" "NAMEDEP&&John's iPhone" 3595 3596>> - <a name="fs3-example-abw-manip-b"></a><font color="red">REQ: black</font> <add|remove> "<number|name>" "<comment>" 3597>> 3598>>> - First check to see if there is already a blacklist entry on file.... 3599 3600>>>> REQ: INFO 4075551212&&WIRELESS 3601>>>> 3602>>>> 403 Start of data defining permitted requests 3603>>>> INFO: alias NOALIAS 3604>>>> INFO: neither 3605>>>> INFO: dial 4075551212&&WIRELESS 3606>>>> 411 End of response 3607>>> 3608>>> - We got `neither` (i.e., not in blacklist nor whitelist) so add it to 3609>>> blacklist based on the <u>number</u> and without a comment.... 3610>>> 3611>>>> REQ: black add "4075551212" "" 3612>>>> 3613>>>> ncidutil "ncidd.blacklist" Blacklist add "4075551212" "" 2>&1 3614>>>> 402 Start of data showing status of handled request 3615>>>> RESP: Modified: ncidd.blacklist 3616>>>> RESP: added: 4075551212 3617>>>> RESP: Done. 3618>>>> 411 End of response 3619>>> 3620>>> - Client sends <font color="red">REQ: RELOAD</font> (not shown) to force 3621>>> server to update the table in the server's memory. 3622>>> 3623>>> - Query the status.... 3624 3625>>>> REQ: INFO 4075551212&&WIRELESS 3626>>>> 3627>>>> 403 Start of data defining permitted requests 3628>>>> INFO: alias NOALIAS 3629>>>> INFO: black number 3630>>>> INFO: dial 4075551212&&WIRELESS 3631>>>> 411 End of response 3632>>> 3633>>> - We got `black number` as expected. 3634>>> 3635>>> - Remove it... 3636 3637>>>> REQ: black remove "4075551212" "" 3638>>>> 3639>>>> ncidutil "ncidd.blacklist" Blacklist remove "4075551212" "" 2>&1 3640>>>> 402 Start of data showing status of handled request 3641>>>> RESP: Modified: ncidd.blacklist 3642>>>> RESP: removed: 4075551212 3643>>>> RESP: Done. 3644>>>> 411 End of response 3645>>> 3646>>> - Other miscellaneous examples that assume the blacklist file is empty and that a 3647>>> <font color="red">REQ: RELOAD</font> (not shown) is done between updates.... 3648>>> 3649>>> - Add a new blacklisted <u>number</u> with a comment.... 3650 3651>>>> REQ: black add "4075551212" "imposter!" 3652>>>> 3653>>>> ncidutil "ncidd.blacklist" Blacklist add "4075551212" \ 3654>>>> "imposter!" 2>&1 3655>>>> 402 Start of data showing status of handled request 3656>>>> RESP: Modified: ncidd.blacklist 3657>>>> RESP: added: 4075551212 # imposter! 3658>>>> RESP: Done. 3659>>>> 411 End of response 3660>>> 3661>>> - Add a new blacklisted <u>name</u> with comment, then request status and notice 3662>>> `black name` in the response.... 3663 3664>>>> REQ: black add "WIRELESS" "telemarketer" 3665>>>> 3666>>>> ncidutil "ncidd.blacklist" Blacklist add "WIRELESS" \ 3667>>>> "telemarketer" 2>&1 3668>>>> 402 Start of data showing status of handled request 3669>>>> RESP: Modified: ncidd.blacklist 3670>>>> RESP: added: WIRELESS # telemarketer 3671>>>> RESP: Done. 3672>>>> 411 End of response 3673>>>> 3674>>>> REQ: RELOAD 3675>>>> 3676>>>> (server responses not shown) 3677>>>> 3678>>>> REQ: INFO 4075551212&&WIRELESS 3679>>>> 3680>>>> 403 Start of data defining permitted requests 3681>>>> INFO: alias NOALIAS 3682>>>> INFO: black name 3683>>>> INFO: dial 4075551212&&WIRELESS 3684>>>> 411 End of response 3685>>> 3686>>> - Add a new blacklisted <u>number</u> with a match name.... 3687 3688>>>> REQ: black add "4075551212" "=Fax machine keeps calling" 3689>>>> 3690>>>> ncidutil "ncidd.blacklist" Blacklist add "4075551212" \ 3691>>>> "=Fax machine keeps calling" 2>&1 3692>>>> 402 Start of data showing status of handled request 3693>>>> RESP: Modified: ncidd.blacklist 3694>>>> RESP: added: 4075551212 #=Fax machine keeps calling 3695>>>> RESP: Done. 3696>>>> 411 End of response 3697 3698>> - <a name="fs3-example-abw-manip-w"></a><font color="red">REQ: white</font> <add|remove> 3699"<number|name>" "<comment>" 3700>> 3701>>> - For the purpose of this example, before adding whitelist entries 3702>>> we'll create a blacklist entry to cover the entire area code 407 3703>>> and include an appropriate comment... 3704 3705>>>> REQ: black add "^407" "blacklist all numbers in area code 407" 3706>>>> 3707>>>> ncidutil "ncidd.blacklist" Blacklist add "^407" \ 3708>>>> "blacklist all numbers in area code 407" 2>&1 3709>>>> 402 Start of data showing status of handled request 3710>>>> RESP: Modified: ncidd.blacklist 3711>>>> RESP: added: ^407 # blacklist all numbers in area code 407 3712>>>> RESP: Done. 3713>>>> 411 End of response 3714>>> 3715>>> - Client sends <font color="red">REQ: RELOAD</font> (not shown) to force 3716>>> server to update the table in the server's memory. 3717>>> 3718>>> - Check the status on two different phone numbers in area code 407... 3719 3720>>>> REQ: INFO 4075551212&&ORLANDO, FL 3721>>>> 3722>>>> 403 Start of data defining permitted requests 3723>>>> INFO: alias NOALIAS 3724>>>> INFO: black number 3725>>>> INFO: dial 4075551212&&ORLANDO, FL 3726>>>> 411 End of response 3727>>>> 3728>>>> REQ: INFO 8002221515&&TOLL FREE 3729>>>> 3730>>>> 403 Start of data defining permitted requests 3731>>>> INFO: alias NOALIAS 3732>>>> INFO: black number 3733>>>> INFO: dial 8002221515&&TOLL FREE 3734>>>> 411 End of response 3735>>> 3736>>> - We got `black number` as expected on both numbers. Add the first one to 3737>>> the whitelist based on the <u>number</u> and without a comment.... 3738>>> 3739>>>> REQ: white add "4075551212" "" 3740>>>> 3741>>>> ncidutil "ncidd.whitelist" Whitelist add "4075551212" "" 2>&1 3742>>>> 402 Start of data showing status of handled request 3743>>>> RESP: Modified: ncidd.whitelist 3744>>>> RESP: added: 4075551212 3745>>>> RESP: Done. 3746>>>> 411 End of response 3747>>>> 3748>>>> REQ: RELOAD 3749>>>> 3750>>>> (server responses not shown) 3751>>>> 3752>>> 3753>>> - Check the status on the numbers again... 3754 3755>>>> REQ: INFO 4075551212&&ORLANDO, FL 3756>>>> 3757>>>> 403 Start of data defining permitted requests 3758>>>> INFO: alias NOALIAS 3759>>>> INFO: white number 3760>>>> INFO: dial 4075551212&&ORLANDO, FL 3761>>>> 411 End of response 3762 3763>>>> REQ: INFO 8002221515&&TOLL FREE 3764>>>> 3765>>>> 403 Start of data defining permitted requests 3766>>>> INFO: alias NOALIAS 3767>>>> INFO: black number 3768>>>> INFO: dial 8002221515&&TOLL FREE 3769>>>> 411 End of response 3770>>> 3771>>> - As expected, we got `white number` on the first one and `black number` on the second. 3772>>> 3773>>> - Remove it... 3774 3775>>>> REQ: white remove "4075551212" "" 3776>>>> 3777>>>> ncidutil "ncidd.whitelist" Whitelist remove "4075551212" "" 2>&1 3778>>>> 402 Start of data showing status of handled request 3779>>>> RESP: Modified: ncidd.whitelist 3780>>>> RESP: removed: 4075551212 3781>>>> RESP: Done. 3782>>>> 411 End of response 3783>>> 3784>>> - Other miscellaneous examples that assume the whitelist file is empty and that a 3785>>> <font color="red">REQ: RELOAD</font> (not shown) is done between updates.... 3786 3787>>> 3788>>> - Add a new whitelisted <u>number</u> with a comment.... 3789 3790>>>> REQ: white add "4075551212" "Lottery Commission" 3791>>>> 3792>>>> ncidutil "ncidd.whitelist" Whitelist add "4075551212" \ 3793>>>> "Lottery Commission" 2>&1 3794>>>> 402 Start of data showing status of handled request 3795>>>> RESP: Modified: ncidd.whitelist 3796>>>> RESP: added: 4075551212 # Lottery Commission 3797>>>> RESP: Done. 3798>>>> 411 End of response 3799>>> 3800>>> - Add a new whitelisted <u>name</u> with comment, then request status and notice 3801>>> `white name` in the response.... 3802 3803>>>> REQ: white add "ORLANDO, FL" "Chamber of Commerce" 3804>>>> 3805>>>> ncidutil "ncidd.whitelist" Whitelist add "ORLANDO, FL" \ 3806>>>> "Chamber of Commerce" 2>&1 3807>>>> 402 Start of data showing status of handled request 3808>>>> RESP: Modified: ncidd.whitelist 3809>>>> RESP: added: "ORLANDO, FL" # Chamber of Commerce 3810>>>> RESP: Done. 3811>>>> 411 End of response 3812>>>> 3813>>>> REQ: RELOAD 3814>>>> 3815>>>> (server responses not shown) 3816>>>> 3817>>>> REQ: INFO 4075551212&&ORLANDO, FL 3818>>>> 3819>>>> 403 Start of data defining permitted requests 3820>>>> INFO: alias NOALIAS 3821>>>> INFO: white name 3822>>>> INFO: dial 4075551212&&ORLANDO, FL 3823>>>> 411 End of response 3824>>> 3825>>> - Add a new whitelisted <u>number</u> with a match name.... 3826 3827>>>> REQ: white add "4075551212" "=Walt Disney World" 3828>>>> 3829>>>> ncidutil "ncidd.whitelist" Whitelist add "4075551212" \ 3830>>>> "=Walt Disney World" 2>&1 3831>>>> 402 Start of data showing status of handled request 3832>>>> RESP: Modified: ncidd.whitelist 3833>>>> RESP: added: 4075551212 #=Walt Disney World 3834>>>> RESP: Done. 3835>>>> 411 End of response 3836 3837>> - <a name="fs3-example-dial"></a> <font color="red">REQ: <DIAL|DIAL_ABORT></font> <number>&&<name>&&<lineid> (new in API 1.6) 3838 3839>> 3840>>> - Check the status of the number the user selected from call history... 3841>>> 3842>>> - Server has NOT been configured to dial the number... 3843 3844>>>> REQ: INFO 4075551212&&WIRELESS&&POTS 3845>>>> 3846>>>> 403 Start of data defining permitted requests 3847>>>> INFO: alias NOALIAS 3848>>>> INFO: neither 3849>>>> INFO: dial NODIAL 3850>>>> 411 End of response 3851>>> 3852 3853>>> - Server HAS been configured to dial the number... 3854 3855>>>> REQ: INFO 4075551212&&WIRELESS&&POTS 3856>>>> 3857>>>> 403 Start of data defining permitted requests 3858>>>> INFO: alias NOALIAS 3859>>>> INFO: neither 3860>>>> INFO: dial 4075551212&&WIRELESS 3861>>>> 411 End of response 3862 3863>>> - User selects option in client to dial the number and chooses 3864>>> the option in the client to add a leading 1 for long distance 3865>>> The dial is successful... 3866 3867>>>> REQ: DIAL 14075551212&&WIRELESS&&POTS 3868>>>> 3869>>>> 402 Start of data showing status of handled request 3870>>>> RESP: Dialed number 14075551212 on line "POTS" 3871>>>> RESP: Pickup phone within 5 seconds 3872>>>> 411 End of response 3873>>>> 3874>>>> RPLY: dial - hungup 14075551212 on line "POTS" 3875 3876>>> - Unsuccessful dial... 3877 3878>>>> REQ: DIAL 14075551212&&WIRELESS&&POTS 3879>>>> 3880>>>> 402 Start of data showing status of handled request 3881>>>> RESP: Dialed number 14075551212 on line "POTS" 3882>>>> RESP: Pickup phone within 5 seconds 3883>>>> 411 End of response 3884>>>> 3885>>>> RPLY: dial - dial failed, modem returned NO DIALTONE 3886 3887>>> - Abort a dial in progress... 3888 3889>>>> REQ: DIAL 14075551212&&WIRELESS&&POTS 3890>>>> 3891>>>> 402 Start of data showing status of handled request 3892>>>> RESP: Dialed number 14075551212 on line "POTS" 3893>>>> RESP: Pickup phone within 5 seconds 3894>>>> 411 End of response 3895 3896>>>> REQ: DIAL_ABORT 14075551212&&WIRELESS&&POTS 3897>>>> 3898>>>> 402 Start of data showing status of handled request 3899>>>> 411 End of response 3900>>>> 3901>>>> RPLY: dial - hungup 14075551212 on line "POTS" 3902 3903>> - <a name="fs3-example-abw-query"></a><font color="red">REQ: INFO</font> <number>&&<name> <br><font color="red">REQ: INFO</font> <number>&&<name>&&<lineid> 3904 3905>>> 3906>>> - This number and name have no alias, blacklist or whitelist entry... 3907>>> 3908>>>> REQ: INFO 4075551212&&WIRELESS 3909>>>> 3910>>>> 403 Start of data defining permitted requests 3911>>>> INFO: alias NOALIAS 3912>>>> INFO: neither 3913>>>> INFO: dial 4075551212&&WIRELESS 3914>>>> 411 End of response 3915 3916>>> 3917>>> - Same as above, except there's also no alias for <lineid> of POTS.... 3918>>> 3919>>>> REQ: INFO 4075551212&&WIRELESS&&POTS 3920>>>> 3921>>>> 403 Start of data defining permitted requests 3922>>>> INFO: alias NOALIAS NOALIAS 3923>>>> INFO: neither 3924>>>> INFO: dial 4075551212&&WIRELESS 3925>>>> 411 End of response 3926>>> 3927>>> - An example showing blacklist and white list entries and aliases based on the number 3928>>> and lineid. The whitelist entry takes precedence over the blacklist of the entire area 3929>>> code; this is why <font color="red">REQ: INFO</font> doesn't report `black number`. 3930>>> For clarity, some server responses to <font color="red">REQ: RELOAD</font> are not shown.... 3931>>> 3932>>>> REQ: RELOAD 3933>>>> 3934>>>> 400 Start of data requiring OK 3935>>>> 3936>>>> INFO: Alias Table: 3937>>>> INFO: Number of Entries: 2 3938>>>> INFO: SLOT TYPE FROM TO DEPEND 3939>>>> INFO: ---- ---- ---- -- ------ 3940>>>> INFO: 000 NAMEDEP * John on Cell "4075551212" 3941>>>> INFO: 001 LINEONLY POTS CELL 3942>>>> 3943>>>> INFO: Blacklist Table: 3944>>>> INFO: Number of Entries: 1 3945>>>> INFO: SLOT ENTRY MATCH NAME 3946>>>> INFO: ---- ----- ---------- 3947>>>> INFO: 000 "^407" 3948>>>> 3949>>>> INFO: Whitelist Table: 3950>>>> INFO: Number of Entries: 1 3951>>>> INFO: SLOT ENTRY MATCH NAME 3952>>>> INFO: ---- ----- ---------- 3953>>>> INFO: 000 "4075551212" 3954>>>> 3955>>>> 410 End of data 3956>>>> 3957>>>> REQ: INFO 4075551212&&WIRELESS 3958>>>> 3959>>>> 403 Start of data defining permitted requests 3960>>>> INFO: alias NAMEDEP 3961>>>> INFO: white number 3962>>>> INFO: dial 4075551212&&WIRELESS 3963>>>> 411 End of response 3964>>>> 3965>>>> REQ: INFO 4075551212&&WIRELESS&&POTS 3966>>>> 3967>>>> 403 Start of data defining permitted requests 3968>>>> INFO: alias NAMEDEP LINEONLY 3969>>>> INFO: white number 3970>>>> INFO: dial 4075551212&&WIRELESS 3971>>>> 411 End of response 3972 3973 3974>> - <a name="fs3-example-abw-reload"></a><font color="red">REQ: RELOAD</font> 3975 3976>>> 3977>>> - Force the NCID server to reload alias, blacklist and whitelist 3978tables from their respective disk files into the server's memory: 3979>>> 3980>>>> REQ: RELOAD 3981>>>> 3982>>>> 400 Start of data requiring OK 3983>>>> INFO: Received Signal 1: Hangup: 1 3984>>>> INFO: Reloading alias, blacklist and whitelist files 3985>>>> INFO: Processed alias file: ncidd.alias 3986>>>> INFO: Alias Table: 3987>>>> INFO: Number of Entries: 6 3988>>>> INFO: SLOT TYPE FROM TO DEPEND 3989>>>> INFO: ---- ---- ---- -- ------ 3990>>>> INFO: 000 NAMEDEP * John on Cell "4075551212" 3991>>>> INFO: 001 LINEONLY POTS CELL 3992>>>> INFO: 002 NMBRONLY 6768048218 Caleb Vinson 3993>>>> INFO: 003 NAMEONLY TOLL FREE TELEMARKETER 3994>>>> INFO: 004 NMBRNAME OUT-OF-AREA UNAVAILABLE 3995>>>> INFO: 005 NMBRDEP * 4075551212 "SMITH JEFF" 3996>>>> INFO: Processed blacklist file: ncidd.blacklist 3997>>>> INFO: Blacklist Table: 3998>>>> INFO: Number of Entries: 18 3999>>>> INFO: SLOT ENTRY MATCH NAME 4000>>>> INFO: ---- ----- ---------- 4001>>>> INFO: 000 "^407" 4002>>>> INFO: 001 "9075551414" "Fax machine keeps calling" 4003>>>> INFO: 002 "2133750923" "FCC bad list 2015-12-14" 4004>>>> INFO: 003 "2133750992" "FCC bad list 2015-12-14" 4005>>>> INFO: 004 "2134150180" "FCC bad list 2015-12-14" 4006>>>> INFO: 005 "2134566756" "FCC bad list 2015-12-14" 4007>>>> INFO: 006 "2134771084" "FCC bad list 2015-12-14" 4008>>>> INFO: 007 "2134879500" "FCC bad list 2015-12-14" 4009>>>> INFO: 008 "2135038127" "FCC bad list 2015-12-14" 4010>>>> INFO: 009 "2139227973" "FCC bad list 2015-12-14" 4011>>>> INFO: 010 "2139925914" "FCC bad list 2015-12-14" 4012>>>> INFO: 011 "2139925916" "FCC bad list 2015-12-14" 4013>>>> INFO: 012 "2139925922" "FCC bad list 2015-12-14" 4014>>>> INFO: 013 "2142284484" "FCC bad list 2015-12-14" 4015>>>> INFO: 014 "2142388242" "FCC bad list 2015-12-14" 4016>>>> INFO: 015 "2142694345" "FCC bad list 2015-12-14" 4017>>>> INFO: 016 "2142698811" "FCC bad list 2015-12-14" 4018>>>> INFO: 017 "2142815189" "FCC bad list 2015-12-14" 4019>>>> INFO: Processed whitelist file: ncidd.whitelist 4020>>>> INFO: Whitelist Table: 4021>>>> INFO: Number of Entries: 3 4022>>>> INFO: SLOT ENTRY MATCH NAME 4023>>>> INFO: ---- ----- ---------- 4024>>>> INFO: 000 "4075551212" 4025>>>> INFO: 001 "4074441992" "Walt Disney World" 4026>>>> INFO: 002 "ORLANDO, FL" 4027>>>> INFO: Reloaded alias, blacklist and whitelist files 4028>>>> 410 End of data 4029 4030 4031>> - <a name="fs3-example-reread"></a><font color="red">REQ: REREAD</font> 4032 4033>>> - Force the server to resend the call log and 4034>>> <font color="red">OPT:</font> lines to the client and if 4035>>> the call log is not empty.... 4036>>> 4037>>>> REQ: REREAD 4038>>>> 4039>>>> CIDLOG: *DATE*12012015*TIME*0028*LINE*POTS*\ 4040>>>> NMBR*2956237064*MESG*NONE*NAME*Minnie Wallace* 4041>>>> HUPLOG: *DATE*12012015*TIME*0105*LINE*POTS*\ 4042>>>> NMBR*2786279268*MESG*NONE*NAME*Sophie Reyes* 4043>>>> ... 4044>>>> 250 End of call log 4045>>>> OPT: hangup-1 4046>>>> OPT: ... 4047>>>> 300 End of connection startup 4048 4049>>> 4050>>> - Force the server to resend the call log and 4051>>> <font color="red">OPT:</font> lines to the client, but if 4052>>> the server is not configured to send the call log.... 4053>>> 4054>>>> REQ: REREAD 4055>>>> 4056>>>> 251 Call log not sent 4057>>>> OPT: hangup-1 4058>>>> OPT: ... 4059>>>> 300 End of connection startup 4060>>> 4061>>> - Force the server to resend the call log and 4062>>> <font color="red">OPT:</font> lines to the client, but if 4063>>> the call log is empty.... 4064>>> 4065>>>> REQ: REREAD 4066>>>> 4067>>>> 252 Call log empty 4068>>>> OPT: hangup-1 4069>>>> OPT: ... 4070>>>> 300 End of connection startup 4071>>> 4072>>> - Force the server to resend the call log and 4073>>> <font color="red">OPT:</font> lines to the client, but if 4074>>> the call log file does not exist... 4075>>> 4076>>>> REQ: REREAD 4077>>>> 4078>>>> 253 No Call log 4079>>>> OPT: hangup-1 4080>>>> OPT: ... 4081>>>> 300 End of connection startup 4082 4083>> - <a name="fs3-example-update"></a><font color="red">REQ: UPDATE</font> 4084 4085>>> 4086>>> - Update the ***current*** call log file with the latest alias changes, 4087>>> store the changes temporarily and present a summary for the user to 4088>>> accept or reject.... 4089>>> 4090>>>> REQ: UPDATE 4091>>>> 4092>>>> cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\ 4093>>>> < /dev/null 2>&1 4094>>>> 401 Start of data requiring ACCEPT or REJECT 4095>>>> INFO: There was 1 change to cidcall.log 4096>>>> INFO: 4097>>>> INFO: (NAMEDEP) Changed "John on Cell" to \ 4098>>>> "John's iPhone" for 4075551212 1 time 4099>>>> 410 End of data 4100>>> 4101>>> - If no changes were found, let the user know and do not prompt to 4102>>> accept or reject.... 4103>>> 4104>>>> REQ: UPDATE 4105>>>> 4106>>>> cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\ 4107>>>> < /dev/null 2>&1 4108>>>> 400 Start of data requiring OK 4109>>>> INFO: There were no changes to cidcall.log 4110>>>> 410 End of data 4111 4112>> - <a name="fs3-example-updates"></a><font color="red">REQ: UPDATES</font> 4113 4114>>> 4115>>> - Update ***all*** call log files with the latest alias changes, 4116>>> store the changes temporarily and present a summary for the user to 4117>>> accept or reject.... 4118>>> 4119>>>> REQ: UPDATES 4120>>>> 4121>>>> cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\ 4122>>>> --multi --ignore1 < /dev/null 2>&1 4123>>>> 401 Start of data requiring ACCEPT or REJECT 4124>>>> INFO: There were 2 changes to cidcall.log 4125>>>> INFO: There were 224 changes to cidcall.log.1 4126>>>> INFO: There were 14 cidcall.log.2 4127>>>> INFO: There were 18 cidcall.log.3 4128>>>> INFO: There were 24 cidcall.log.4 4129>>>> INFO: There were 16 cidcall.log.5 4130>>>> INFO: 4131>>>> INFO: (NAMEDEP) Changed "John on Cell" to \ 4132>>>> "John's iPhone" for 4075551212 298 times 4133>>>> 410 End of data 4134>>> 4135>>> - If no changes were found, let the user know and do not prompt to 4136>>> accept or reject.... 4137>>> 4138>>>> REQ: UPDATES 4139>>>> 4140>>>> cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\ 4141>>>> --multi < /dev/null 2>&1 4142>>>> 400 Start of data requiring OK 4143>>>> INFO: There were no changes to cidcall.log 4144>>>> 410 End of data 4145 4146 4147>> - <a name="fs3-example-wrk-log-accept"></a><font color="red">WRK: ACCEPT LOG</font> 4148 4149>>> 4150>>> - Alias changes have been applied to a temporary copy of the ***current*** 4151>>> call log file and the user has **accepted** the changes. This causes the server 4152>>> to replace the ***current*** call log file with the temporary copy. No further 4153>>> interaction with the user is needed. 4154>>> 4155>>>> REQ: UPDATE 4156>>>> 4157>>>> cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\ 4158>>>> < /dev/null 2>&1 4159>>>> 401 Start of data requiring ACCEPT or REJECT 4160>>>> INFO: There was 1 change to cidcall.log 4161>>>> INFO: 4162>>>> INFO: (NAMEDEP) Changed "John on Cell" to \ 4163>>>> "John's iPhone" for 4075551212 1 time 4164>>>> 410 End of data 4165>>>> 4166>>>> WRK: ACCEPT LOG 4167>>>> 4168>>>> mv cidcall.log.new cidcall.log 4169 4170>> - <a name="fs3-example-wrk-log-reject"></a><font color="red">WRK: REJECT LOG</font> 4171 4172>>> 4173>>> - Alias changes have been applied to a temporary copy of the ***current*** 4174>>> call log file and the user has **rejected** the changes. This causes 4175>>> the server to remove the temporary copy of the ***current*** call log 4176>>> file. No further interaction with the user is needed. 4177>>> 4178>>>> REQ: UPDATE 4179>>>> 4180>>>> cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\ 4181>>>> < /dev/null 2>&1 4182>>>> 401 Start of data requiring ACCEPT or REJECT 4183>>>> INFO: There was 1 change to cidcall.log 4184>>>> INFO: 4185>>>> INFO: (NAMEDEP) Changed "John on Cell" to \ 4186>>>> "John's iPhone" for 4075551212 1 time 4187>>>> 410 End of data 4188>>>> 4189>>>> WRK: REJECT LOG 4190>>>> 4191>>>> rm cidcall.log.new 4192 4193>> - <a name="fs3-example-wrk-logs-accept"></a><font color="red">WRK: ACCEPT LOGS</font> 4194 4195>>> 4196>>> - Alias changes have been applied to temporary copies of ***all*** 4197>>> call log files and the user has **accepted** the changes. This causes the server 4198>>> to replace the existing call log files with the temporary copies. No further 4199>>> interaction with the user is needed. 4200>>> 4201>>>> REQ: UPDATES 4202>>>> 4203>>>> cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\ 4204>>>> --multi --ignore1 < /dev/null 2>&1 4205>>>> 401 Start of data requiring ACCEPT or REJECT 4206>>>> INFO: There were 2 changes to cidcall.log 4207>>>> INFO: There were 224 changes to cidcall.log.1 4208>>>> INFO: There were 14 cidcall.log.2 4209>>>> INFO: There were 18 cidcall.log.3 4210>>>> INFO: There were 24 cidcall.log.4 4211>>>> INFO: There were 16 cidcall.log.5 4212>>>> INFO: 4213>>>> INFO: (NAMEDEP) Changed "John on Cell" to \ 4214>>>> "John's iPhone" for 4075551212 298 times 4215>>>> 410 End of data 4216>>>> 4217>>>> WRK: ACCEPT LOGS 4218>>>> 4219>>>> for f in cidcall.log.*[0-9]; do mv $f.new $f; done 4220>>>> mv cidcall.log.new cidcall.log 4221 4222>> - <a name="fs3-example-wrk-logs-reject"></a><font color="red">WRK: REJECT LOGS</font> 4223 4224>>> 4225>>> - Alias changes have been applied to temporary copies of ***all*** 4226>>> call log files and the user has **rejected** the changes. This causes 4227>>> the server to remove the temporary copies of ***all*** call log 4228>>> files. No further interaction with the user is needed. 4229>>> 4230>>>> REQ: UPDATES 4231>>>> 4232>>>> cidupdate -a ncidd.alias -c cidcall.log < /dev/null 2>&1\ 4233>>>> --multi --ignore1 < /dev/null 2>&1 4234>>>> 401 Start of data requiring ACCEPT or REJECT 4235>>>> INFO: There were 2 changes to cidcall.log 4236>>>> INFO: There were 224 changes to cidcall.log.1 4237>>>> INFO: There were 14 cidcall.log.2 4238>>>> INFO: There were 18 cidcall.log.3 4239>>>> INFO: There were 24 cidcall.log.4 4240>>>> INFO: There were 16 cidcall.log.5 4241>>>> INFO: 4242>>>> INFO: (NAMEDEP) Changed "John on Cell" to \ 4243>>>> "John's iPhone" for 4075551212 298 times 4244>>>> 410 End of data 4245>>>> 4246>>>> WRK: REJECT LOGS 4247>>>> 4248>>>> rm cidcall.log.*.new 4249>>>> rm cidcall.log.new 4250 4251<!-- 4252[## Feature Set 4: Acknowledgment Support] 4253--> 4254 4255## <a name="fs4-ack-support"></a> Feature Set 4: Acknowledgment Support 4256 4257> You might want to implement this feature set if the network connection 4258 between a client/gateway and the server suffers from reliability issues. 4259 4260> A client/gateway can ask the server to <font color="red">ACK:</font>(nowledge) 4261all lines sent to it. Normally only used when a smartphone is involved. 4262Requires a Feature Set 2 server. 4263 4264 4265> A client/gateway can also ask the server to respond to a periodic 4266 <font color="red">REQ: YO</font> request to make sure the communication to 4267 the server is still there. 4268 4269<!-- 4270[### FS4: SERVER IMPLEMENTATION] 4271--> 4272 4273> ### <a name="fs4-server-impl"></a> SERVER IMPLEMENTATION 4274 4275>> If you want to implement a server to take advantage of 4276acknowledgments: 4277 4278>> - implement a Feature Set 1 server 4279 4280>> - implement a Feature Set 2 server if a <font color="red">REQ: 4281ACK</font> is required 4282 4283>> - only send <font color="red">ACK:</font> lines in response to the specific 4284client/gateway connection that sent the <font color="red">REQ: ACK</font> or 4285<font color="red">REQ: YO</font> 4286 4287<!-- 4288[### FS4: Server Output Lines] 4289--> 4290 4291>> ### <a name="fs4-server-output"></a> Server Output Lines 4292 4293>> - <a name="line-type-ack"></a><font color="red">ACK:</font> <line to be sent> 4294 4295>>> where <line to be sent> is an exact copy of what the server just received 4296 4297>>> An <font color="red">ACK:</font> is sent under two different scenarios: 4298 4299>>> - Whenever the server receives a <font color="red">REQ: ACK</font> line 4300*and also* all subsequent lines received for the duration of the connection. 4301Requires a Feature Set 2 server. 4302 4303>>>> 4304 ACK: REQ: ACK 4305 ACK: CALL: ###DATE... 4306 ACK: NOT: <message> 4307 ACK: CALLINFO: ###END ... 4308 4309>>> - Every time the server receives a <font color="red">REQ: YO</font> line. 4310 4311>>>> `ACK: REQ: YO` 4312 4313<!-- 4314[### FS4: GATEWAY IMPLEMENTATION] 4315--> 4316 4317> ### <a name="fs4-gw-impl"></a> GATEWAY IMPLEMENTATION 4318 4319>> - implement a Feature Set 2 gateway 4320 4321>> - if desired, send <font color="red">REQ: ACK</font> to the server to enable 4322acknowledgment of all lines 4323 4324>> - gateways are allowed to send a <font color="red">REQ: YO</font> to 4325the server for an <font color="red">ACK: REQ: YO</font> response. The response 4326indicates the server is still available. It should be sent only after at 4327least 15 minutes of no server activity. 4328 4329 4330<!-- 4331[### FS4: Gateway-to-Server] 4332--> 4333 4334>> ### <a name="fs4-gw2server"></a> Gateway-to-Server 4335 4336>> - <a name="line-type-req-ack-gateway"></a><font color="red">REQ: ACK</font> 4337 4338>>> Enables the server to generate an <font color="red">ACK:</font> on each 4339subsequent line sent to the server, including the 4340<font color="red">REQ: ACK</font> request. This only needs to be sent 4341once by the gateway's connection; it remains enabled until the gateway 4342disconnects. 4343 4344>>>> `REQ: ACK` 4345 4346>> - <a name="line-type-req-yo-gateway"></a><font color="red">REQ: YO</font> 4347 4348>>> A request to the server for an <font color="red">ACK:</font> to make 4349sure communication with the server is active. 4350 4351 4352>>>> `REQ: YO` 4353 4354 4355<!-- 4356[### FS4: CLIENT IMPLEMENTATION] 4357--> 4358 4359> ### <a name="fs4-client-impl"></a> CLIENT IMPLEMENTATION 4360 4361>> - implement a Feature Set 1 client 4362 4363>> - implement a Feature Set 2 client if a <font color="red">REQ: 4364ACK</font> is required 4365 4366>> - clients are allowed to send a <font color="red">REQ: YO</font> to 4367the server for an <font color="red">ACK: REQ: YO</font> response. The response 4368indicates the server is still available. It should be sent only after at 4369least 15 minutes of no server activity. 4370 4371<!-- 4372[### FS4: Client-to-Server] 4373--> 4374 4375>> ### <a name="fs4-client2server"></a> Client-to-Server 4376 4377>> - <a name="line-type-req-ack-client"></a><font color="red">REQ: ACK</font> 4378 4379>>> Enables the server to generate an <font color="red">ACK:</font> on each 4380subsequent line sent to the server, including the 4381<font color="red">REQ: ACK</font> request. This only needs to be sent 4382once by the client's connection; it remains enabled until the client 4383disconnects. 4384 4385>>>> `REQ: ACK` 4386 4387>> - <a name="line-type-req-yo-client"></a><font color="red">REQ: YO</font> 4388 4389>>> A request to the server for an <font color="red">ACK:</font> to make 4390sure communication with the server is active. 4391 4392>>>> `REQ: YO` 4393 4394<!-- 4395[## Feature Set 5: Relay Job Support] 4396--> 4397 4398## <a name="fs5-relay-job-support"></a> Feature Set 5: Relay Job Support (new in API 1.4) 4399 4400> Relay Jobs allow clients and gateways to query and control other clients 4401 and gateways. Compare this with Feature Set 3 Client Jobs where clients 4402 query and/or control only the server, e.g., adding new numbers to 4403 **ncidd.blacklist**. 4404 4405<!-- 4406[### FS5: RELAY JOB OVERVIEW] 4407--> 4408 4409 4410> ### <a name="fs5-overview"></a> RELAY JOB OVERVIEW 4411 4412> Relay Jobs were originally conceived as a way for NCIDpop to ask a user 4413 for an SMS phone number and an SMS text message to be sent using 4414 NCID Android running on a smartphone. With the 4415 <font color="red">NOT:</font> line type, smartphones could already 4416 forward SMS messages to connected NCID clients -- one 4417 direction only. Relay Jobs allow NCID clients like NCIDpop to "remotely" 4418 create new SMS messages for sending via smartphones. 4419 (See [Appendix E: SMS Relay Job sequence diagram](#ncidpop-sms-relay).) 4420 4421> After the initial SMS design, the Relay Job concept was expanded to 4422 allow querying the status of certain smartphone properties (e.g., 4423 battery level) and to control the smartphone's behavior in limited 4424 ways (e.g., dial a phone number). 4425 4426> With the final design described below, Relay Jobs are no longer limited 4427 to querying/controlling smartphones; the Relay Job specification is now 4428 generic enough that other clients and gateways can be queried/controlled. 4429 4430> A Relay Job consists of three primary pieces of information: 4431 4432> - a Relay Job Origin (RJO) device (or client/gateway) name 4433 4434> - a Relay Job Target (RJT) device (or client/gateway) name 4435 4436> - a command to be executed (arguments are included if required) 4437 4438> RJO and RJT device names should be unique (this is not strictly enforced) 4439 and are normally configured manually by the user within the NCID client 4440 or gateway program. (Quite often the RJT name will be the same value used 4441 to populate the LINE\*<lineid> field pair for non-<font color="red">RLY:</font> 4442 line types.) If there is no way for the user to set the device name, 4443 or it's deemed unnecessary, then the default device name is usually the 4444 output of the **hostname** program on Unix/Linux, or the Computer name 4445 under Windows. When the NCID server sends the Relay Job to all listening 4446 clients and gateways, each client/gateway compares its device name against 4447 the RJT. A special target of '@all' is allowed and, assuming the target 4448 can execute the Relay Job command, any and all appropriate targets will 4449 carry it out. 4450 4451<br> 4452 4453> What queries/actions are allowed is entirely up to the capability of 4454 the RJT. (For example, a wifi-only tablet would not be able to dial a 4455 phone number but its battery level could probably be queried.) For this 4456 reason, this API document can only suggest possible commands that could 4457 be used; the NCID server doesn't care what they are. 4458 4459> If a target is not enabled for Relay Jobs, or if it is enabled but 4460 is unable to execute the Relay Job command (e.g., the wifi-only tablet 4461 can't dial a number), then the target will simply ignore the Relay Job. 4462 4463> The NCID server's only role is to be the middle man and "relay" these 4464 jobs from an RJO to all listening clients and gateways. 4465 4466<!-- 4467[### FS5: SERVER IMPLEMENTATION] 4468--> 4469 4470> ### <a name="fs5-server-impl"></a> SERVER IMPLEMENTATION 4471 4472>> If you want to implement a server to handle Relay Jobs: 4473 4474>> - implement a Feature Set 1 server 4475 4476>> - if a client or gateway sends a line where the first field pair is 4477>> prefixed with <font color="red">###</font>, replace <font color="red">\#\#\#</font> 4478>> with <font color="red">\*\*\*</font> and send it to all connected 4479>> clients and gateways 4480 4481>> - if the server is configured to send the call log, change the 4482>> <font color="red">RLY:</font> label to be <font color="red">RLYLOG:</font> 4483 4484<!-- 4485[### FS5: RELAY JOB ORIGIN (RJO) IMPLEMENTATION] 4486--> 4487 4488> ### <a name="fs5-origin-impl"></a> RELAY JOB ORIGIN (RJO) IMPLEMENTATION 4489 4490>> An RJO is typically considered to be a client and not a gateway because 4491 clients interact with a user. However, gateways can also be RJOs. 4492 4493>> If you want to implement a client or gateway to *initiate* Relay Jobs: 4494 4495>> - when connecting to the server, be sure the server indicates it is 4496 enabled for Feature Set 5 4497 4498>> - ignore (do not display) <font color="red">RLY:</font> lines where 4499 the RJO matches itself 4500 4501>> - ignore (do not display) <font color="red">RLYLOG:</font> lines 4502 4503>> - provide a way for the user to specify the RJT, or '@all', that is 4504 to execute the Relay Job 4505 4506>> - provide a way for the user to type in, or select from a list, a 4507 CMD to be sent to the target, along with any required arguments 4508 4509<!-- 4510[### FS5: RJO Line Type Definition] 4511--> 4512 4513<br> 4514 4515> ### <a name="fs5-def-rjo"></a> RJO Line Type Definition 4516 4517> - <a name="line-type-rly-rjo"></a><font color="red">RLY:</font> 4518 4519>> A Relay Job sent to the server. 4520 4521>>> `RLY: <message> ###DATE*<date>*TIME*<time>*TO*<target>*FROM*<origin>*CMD*<command>*` 4522 4523>>> `RLY: <message> ###DATE*<date>*TIME*<time>*TO*<target>*FROM*<origin>*CMD*<command>*ARG1*<arg1>*` 4524 4525>>> `RLY: <message> ###DATE*<date>*TIME*<time>*TO*<target>*FROM*<origin>*CMD*<command>*ARG1*<arg1>*ARG2*<arg2>*...` 4526 4527>> <message> is optional and depends on <command>. 4528 4529>> The <font color="red">RLY:</font> line has the following field pairs 4530(field label and field data): 4531 4532>>> 4533 <label>\*<data>\* | Description 4534 ------------------|:-------------------------------------------------------- 4535 \#\#\# | start of the information part of the message being sent to the server 4536 DATE\*date\* | where date is [mmddyyyy or ddmmyyyy](#gen-datetime), m = month, d = day, y = year 4537 TIME\*time\* | where time is [hhmm in 24-hour format](#gen-datetime), h = hour, m = minute 4538 TO\*target\* | where target is a case-sensitive [string of characters](#gen-text) or '@all' 4539 FROM\*origin\* | where origin is a case-sensitive [string of characters](#gen-text) 4540 CMD\*command\* | where command is a case-sensitive [string of characters](#gen-text) 4541 ARG1\*arg1\* | optional field pair where arg1 is a [string of characters](#gen-text) 4542 ARG2\*arg2\* | optional field pair where arg2 is a [string of characters](#gen-text) 4543 ... | ... 4544 ARGx\*argx\* | optional field pair where argx is a [string of characters](#gen-text) 4545 4546<br> 4547<br> 4548<br> 4549<br> 4550 4551>> The following are some suggestions for <command>: 4552 4553>>> 4554 <command> | <arg1> |Description 4555 ----------------|---------------------|:------------------ 4556 BATTERY | |reply with the battery level in a <font color="red">NOT:</font> 4557 LOCATION | |reply with the GPS location in a <font color="red">NOT:</font> 4558 PLACECALL | <phone number>|remotely dial <phone number> 4559 RINGTONE | |play the default ringtone to help find the smartphone, or just to annoy someone 4560 TEXTMSG | <phone number>|send an SMS <message> to <phone number> 4561 4562<!-- 4563[### FS5: RELAY JOB TARGET (RJT) IMPLEMENTATION] 4564--> 4565 4566> ### <a name="fs5-target-impl"></a> RELAY JOB TARGET (RJT) IMPLEMENTATION 4567 4568>> An RJT is typically considered to be a gateway and not a client because 4569 gateways usually do not interact with a user. However, clients can also 4570 be RJTs. 4571 4572>> If you want to implement a client or gateway to *take action* on Relay Jobs: 4573 4574>> - provide a way for the user to specify the RJT 4575 4576>> - when connecting to the server, be sure the server indicates it is 4577 enabled for Feature Set 5 4578 4579>> - ignore (do not display) <font color="red">RLY:</font> lines where 4580 the RJO matches itself 4581 4582>> - ignore (do not display) <font color="red">RLYLOG:</font> lines 4583 4584>> - ignore (do not display) <font color="red">RLY:</font> lines where 4585 the RJT is not '@all' and the RJT does not match itself 4586 4587>> - execute the job's command and use <font color="red">MSG:</font> or 4588 <font color="red">NOT:</font> line types to send the result back to 4589 the server 4590 4591> ### <a name="fs5-def-rjt"></a> RJT Line Type Definition 4592 4593> - <a name="line-type-rly-rjt"></a><font color="red">RLY:</font> 4594 4595>> A Relay Job sent to all listening clients and gateways. It is the same 4596 as the [RJO Line Type Definition](#fs5-def-rjo) except instead of 4597 \#\#\# before the first field pair, the server changes it to \*\*\*. 4598 4599 4600<!-- 4601[### FS5: RELAY JOB EXAMPLES 4602--> 4603 4604> ### <a name="fs5-examples"></a> RELAY JOB EXAMPLES 4605 4606>> The following examples are based on a setup with four devices: 4607 4608>> - Windows desktop named "Winny" running NCIDpop 4609 4610>> - Android wi-fi only tablet named "Tabby" running NCID Android 4611 4612>> - Android smartphone named "Smarty" running NCID Android 4613 4614>> - Raspberry Pi named "CrayWannaBe" running NCID server 4615 4616>> ##### CMD\*BATTERY\* 4617 4618>> - Request Tabby's battery level: 4619 4620>>> 4621 Program | Device | Entry in ncidd.log 4622 -------------|-------------|:---------- 4623 NCIDpop | Winny | RLY: \#\#\#DATE\*09052016\*TIME\*0111\*TO\*Tabby<br>\*FROM\*Winny\*CMD\*BATTERY\* 4624 ncidd | CrayWannaBe | RLY: \*\*\*DATE\*09052016\*TIME\*0111\*TO\*Tabby<br>\*FROM\*Winny\*CMD\*BATTERY\* 4625 NCID Android | Tabby | NOT: Battery is 100.0% (Full) \#\#\#DATE\*09052016<br>\*TIME\*0111\*NAME\*-\*NMBR\*-\*LINE\*Tabby\*MTYPE\*IN\* 4626 ncidd | CrayWannaBe | NOT: Battery is 100.0% (Full) \*\*\*DATE\*09052016<br>\*TIME\*0111\*NAME\*-\*NMBR\*-\*LINE\*Tabby\*MTYPE\*IN\* 4627 4628>> - Request battery level from all NCID Android devices: 4629 4630>>> 4631 Program | Device | Entry in ncidd.log 4632 -------------|-------------|:---------- 4633 NCIDpop | Winny | RLY: \#\#\#DATE\*09052016\*TIME\*0111\*TO\*@all<br>\*FROM\*Winny\*CMD\*BATTERY\* 4634 ncidd | CrayWannaBe | RLY: \*\*\*DATE\*09052016\*TIME\*0111\*TO\*@all<br>\*FROM\*Winny\*CMD\*BATTERY\* 4635 NCID Android | Tabby | NOT: Battery is 100.0% (Full) \#\#\#DATE\*09052016<br>\*TIME\*0111\*NAME\*-\*NMBR\*-\*LINE\*Tabby\*MTYPE\*IN\* 4636 4637<br> 4638 4639>>> 4640 Program | Device | Entry in ncidd.log 4641 -------------|-------------|:---------- 4642 ncidd | CrayWannaBe | NOT: Battery is 100.0% (Full) \*\*\*DATE\*09052016<br>\*TIME\*0111\*NAME\*-\*NMBR\*-\*LINE\*Tabby\*MTYPE\*IN\* 4643 NCID Android | Smarty | NOT: Battery is 84.0% (Discharging) \#\#\#DATE<br>\*09052016\*TIME\*0111\*NAME\*-\*NMBR\*-\*LINE\*Smarty\*MTYPE\*IN\* 4644 ncidd | CrayWannaBe | NOT: Battery is 84.0% (Discharging) \*\*\*DATE<br>\*09052016\*TIME\*0111\*NAME\*-\*NMBR\*-\*LINE\*Smarty\*MTYPE\*IN\* 4645 4646>> ##### CMD\*LOCATION\* 4647 4648>> - Request Smarty's GPS coordinates: 4649 4650>>> 4651 Program | Device | Entry in ncidd.log 4652 -------------|-------------|:---------- 4653 NCIDpop | Winny | RLY: \#\#\#DATE\*09052016\*TIME\*1330\*TO\*Smarty<br>\*FROM\*Winny\*CMD\*LOCATION\* 4654 ncidd | CrayWannaBe | RLY: \*\*\*DATE\*09052016\*TIME\*1330\*TO\*Smarty<br>\*FROM\*Winny\*CMD\*LOCATION\* 4655 NCID Android | Smarty | NOT: Location is: latitude 45.57175012, longitude -122.67063299 \#\#\#DATE\*09052016\*TIME\*1330\*NAME\*-\*NMBR\*-\*LINE\*Smarty\*MTYPE\*IN\* 4656 ncidd | CrayWannaBe | NOT: Location is: latitude 45.57175012, longitude -122.67063299 \*\*\*DATE\*09052016\*TIME\*1330\*NAME\*-\*NMBR\*-\*LINE\*Smarty\*MTYPE\*IN\* 4657 4658<br> 4659<br> 4660<br> 4661<br> 4662 4663>> ##### CMD\*PLACECALL\* 4664 4665>> - Remotely dial a number on Smarty: 4666 4667>>> 4668 Program | Device | Entry in ncidd.log 4669 -------------|-------------|:---------- 4670 NCIDpop | Winny | RLY: \#\#\#DATE\*09052016\*TIME\*1751\*TO\*Smarty<br>\*FROM\*Winny\*CMD\*PLACECALL\*ARG1<br>\*4075557777\* 4671 ncidd | CrayWannaBe | RLY: \*\*\*DATE\*09052016\*TIME\*1751\*TO\*Smarty<br>\*FROM\*Winny\*CMD\*PLACECALL\*ARG1<br>\*4075557777\* 4672 NCID Android | Smarty | CALL: \#\#\#DATE09061751...CALLOUT...LINESmarty<br>...NMBR4075557777...NAMEJOHN ON CELL+++ 4673 ncidd | CrayWannaBe | OUT: \*DATE\*09062016\*TIME\*1751\*LINE\*Smarty<br>\*NMBR\*4075557777\*MESG\*NONE\*NAME<br>\*JOHN ON CELL\* 4674 NCID Android | Smarty | CALLINFO: \#\#\#BYE...DATE09061751<br>...SCALL09/06/2016 17:51:12...ECALL09/06/2016 17:58:09...CALLOUT...LINESmarty<br>...NMBR4075557777...NAMEJOHN ON CELL+++ 4675 ncidd | CrayWannaBe | END: \*HTYPE\*BYE\*DATE\*09062016\*TIME<br>\*1751\*SCALL\*09/06/2016 17:51:12\*ECALL<br>\*09/06/2016 17:58:09\*CTYPE\*OUT\*LINE\*Smarty<br>\*NMBR\*4075557777\*NAME\*JOHN ON CELL\* 4676 4677>> ##### CMD\*RINGTONE\* 4678 4679>> - Remotely play Smarty's default ringtone: 4680 4681>>> 4682 Program | Device | Entry in ncidd.log 4683 -------------|-------------|:---------- 4684 NCIDpop | Winny | RLY: \#\#\#DATE\*09052016\*TIME\*1241\*TO\*Smarty<br>\*FROM\*Winny\*CMD\*RINGTONE\* 4685 ncidd | CrayWannaBe | RLY: \*\*\*DATE\*09052016\*TIME\*1241\*TO\*Smarty<br>\*FROM\*Winny\*CMD\*RINGTONE\* 4686 4687<br> 4688<br> 4689 4690>> ##### CMD\*TEXTMSG\* 4691 4692>> - Use NCIDpop to remotely send an SMS from Smarty: 4693 4694>>> 4695 Program | Device | Entry in ncidd.log 4696 -------------|-------------|:---------- 4697 NCIDpop | Winny | RLY: Are you coming over to see the surprise eclipse<br> tonight?\#\#\#DATE\*09052016\*TIME\*2138\*TO<br>\*Smarty\*FROM\*Winny\*CMD\*TEXTMSG\*ARG1<br>\*4075557777\* 4698 ncidd | CrayWannaBe | RLY: Are you coming over to see the surprise eclipse<br> tonight?\*\*\*DATE\*09052016\*TIME\*2138\*TO<br>\*Smarty\*FROM\*Winny\*CMD\*TEXTMSG\*ARG1<br>\*4075557777\* 4699 NCID Android | Smarty | NOT:Are you coming over to see the surprise eclipse<br> tonight?\#\#\#DATE\*09062016\*TIME\*2138\*NAME<br>\*JOHN ON CELL\*NMBR\*14075557777\*LINE\*Smarty<br>\*MTYPE\*OUT\* 4700 ncidd | CrayWannaBe | NOT:Are you coming over to see the surprise eclipse<br> tonight?\*\*\*DATE\*09062016\*TIME\*2138\*NAME<br>\*JOHN ON CELL\*NMBR\*14075557777\*LINE\*Smarty<br>\*MTYPE\*OUT\* 4701 4702<!-- 4703[## Sending a Text Message] 4704--> 4705 4706## <a name="sending-messages"></a> Sending a Text Message 4707 4708> The server accepts a single line text message from a client and 4709broadcasts it to all connected clients. All messages must begin with the 4710<font color="red">MSG:</font> label. 4711 4712> Other programs such as netcat can be used to send a message. Telnet is 4713not recommended. If netcat is used, please note there are different 4714versions with different options. 4715 4716> This shell script example creates a 10 minute food timer. The -w1 is a 4717one second idle timeout to wait before disconnect: 4718 4719 4720>> sleep 600; echo "MSG: Food Ready" | nc -w1 localhost 3333 > /dev/null 4721 4722> (New in API 1.5) At connect, you can send zero or more <font color="red">HELLO:</font> lines 4723 prior to a <font color="red">MSG:</font> line. In particular, sending 4724 a <font color="red">HELLO: CMD: no_log</font> line can improve performance 4725 because it forces the server not to send the call log before processing the 4726 <font color="red">MSG:</font>. 4727 4728>> sleep 600; \ 4729>> echo -e "HELLO: IDENT: client food timer 1.1\nHELLO: \ 4730>> CMD: no_log\nMSG: Food Ready" | nc -w1 localhost 3333 > /dev/null 4731 4732 4733<!-- 4734[## Country Codes] 4735--> 4736 4737## <a name="country-codes"></a> Country Codes 4738 4739> Country codes tell the client how to display the telephone number, 4740especially when the area code and number each have a varying number of 4741digits. The Country Codes supported in the client are shown in the table 4742below. The NONE country code leaves the number unformatted. Feel free to 4743request more country codes. 4744 4745> See <http://www.iso.org/iso/english_country_names_and_code_elements> for the 4746two letter country codes. 4747> 4748 Country |Country Code |Area Code URL 4749 ----------------|--------------|------------- 4750 Croatia |HR | [https://en.wikipedia.org/wiki/<br>Telephone\_numbers\_in\_Croatia](https://en.wikipedia.org/wiki/Telephone\_numbers\_in\_Croatia) 4751 France |FR | [https://en.wikipedia.org/wiki/<br>Telephone\_numbers\_in\_France](https://en.wikipedia.org/wiki/Telephone\_numbers\_in\_France) 4752 Germany |DE | [https://en.wikipedia.org/wiki/<br>Area\_codes\_in\_Germany](https://en.wikipedia.org/wiki/Area\_codes\_in\_Germany) 4753 Sweden |SE | [https://en.wikipedia.org/wiki/<br>Telephone\_numbers\_in\_Sweden](https://en.wikipedia.org/wiki/Telephone\_numbers\_in\_Sweden) 4754 United Kingdom |UK | [https://en.wikipedia.org/wiki/<br>United\_Kingdom\_area\_codes](https://en.wikipedia.org/wiki/United\_Kingdom\_area\_codes) 4755 United States |US | [https://en.wikipedia.org/wiki/<br>North\_American\_Numbering\_Plan](https://en.wikipedia.org/wiki/North\_American\_Numbering\_Plan) 4756 NONE |NONE | 4757 4758<!-- 4759[## Emulation Programs and Test Files] 4760--> 4761 4762## <a name="emulation"></a> Emulation Programs and Test Files 4763 4764> The **test** directory in the NCID source contains emulation programs 4765for the server, client, SIP gateway and modem. There are also test 4766files for the server and a client logfile used for screenshots in the 4767source test directory. The **README-test** file explains how to use the 4768emulation programs and test files. 4769 4770<!-- 4771[## Appendix A: Copy-and-paste friendly {CALLTYPES} and {MSGTYPES}] 4772--> 4773 4774## <a name="quick-ref-call-types"></a> Appendix A: Copy-and-paste friendly {CALLTYPES} and {MSGTYPES} 4775 4776> For development purposes, here are non-clickable, copy-and-paste 4777friendly versions all on one line. These are the types likely to be used 4778when creating new client output modules. 4779 4780>> 4781>> No colons: 4782 4783>>> Space delimited: 4784>>> <font color="red">BLK CID HUP MSG MWI NOT OUT PID PUT RID WID</font> 4785<p> 4786 4787>>> Comma delimited: 4788>>> <font color="red">BLK,CID,HUP,MSG,MWI,NOT,OUT,PID,PUT,RID,WID</font> 4789<p> 4790 4791>>> Comma and space delimited: 4792>>> <font color="red">BLK, CID, HUP, MSG, MWI, NOT, OUT, PID, PUT, RID, WID</font> 4793<p> 4794 4795>>> Pipe delimited: 4796>>> <font color="red">BLK|CID|HUP|MSG|MWI|NOT|OUT|PID|PUT|RID|WID</font> 4797<p> 4798 4799>>> Regex-ready, pipe delimited: 4800>>> <font color="red">^BLK|^CID|^HUP|^MSG|^MWI|^NOT|^OUT|^PID|^PUT|^RID|^WID</font> 4801<p> 4802 4803 4804>> With colons: 4805 4806>>> Space delimited: 4807>>> <font color="red">BLK: CID: HUP: MSG: MWI: NOT: OUT: PID: PUT: RID: WID:</font> 4808<p> 4809 4810>>> Comma delimited: 4811>>> <font color="red">BLK:,CID:,HUP:,MSG:,MWI:,NOT:,OUT:,PID:,PUT:,RID:,WID:</font> 4812<p> 4813 4814>>> Comma and space delimited: 4815>>> <font color="red">BLK:, CID:, HUP:, MSG:, MWI:, NOT:, OUT:, PID:, PUT:, RID:, WID:</font> 4816<p> 4817 4818>>> Pipe delimited: 4819>>> <font color="red">BLK:|CID:|HUP:|MSG:|MWI:|NOT:|OUT:|PID:|PUT:|RID:|WID:</font> 4820<p> 4821 4822>>> Regex-ready, pipe delimited: 4823>>> <font color="red">^BLK:|^CID:|^HUP:|^MSG:|^MWI:|^NOT:|^OUT:|^PID:|^PUT:|^RID:|^WID:</font> 4824<p> 4825 4826<!-- 4827[## Appendix B: Index of line type definitions] 4828--> 4829 4830## <a name="index-line-types"></a> Appendix B: Index of line type definitions 4831 4832 4833> 4834Table column| Description 4835------------|------------- 4836FS | Applicable Feature Set 4837History? | Yes if saved to call history log 4838Modules? | Yes if sent to client output modules 4839Forwarded? | Line type that is sent to forwarding gateway 4840 4841> Arranged alphabetically. 4842> 4843> 4844>Click on the *Line type* <font color="red">XXX</font> to be taken to its 4845definition. 4846> 4847>Not included below are <font color="red">XXXLOG:</font> line types. 4848If the *History?* column is *Yes*, then when the server sends the call 4849history log, it replaces the <font color="red">XXX:</font> label with 4850<font color="red">XXXLOG:</font>. Clients parse <font color="red">XXXLOG:</font> 4851as if they were <font color="red">XXX:</font>. 4852 4853 4854> 4855> 4856>Line type | FS | History? | Modules? | Forwarded? 4857>:--------- |----|:--------:|:--------:|:---------- 4858>[<font color="red">\\n (newline)</font>](#line-type-newline) | 1 | | | 4859>[<font color="red">200</font>](#line-type-200) | 1 | | | 4860>[<font color="red">210</font>](#line-type-210) | 1 | | | 4861>[<font color="red">250</font> - <font color="red">253</font>](#line-type-25x) | 1 | | | 4862>[<font color="red">300</font>](#line-type-300) | 1 | | | 4863>[<font color="red">400</font>](#line-type-400) | 3 | | | 4864>[<font color="red">401</font>](#line-type-401) | 3 | | | 4865>[<font color="red">402</font>](#line-type-402) | 3 | | | 4866>[<font color="red">403</font>](#line-type-403) | 3 | | | 4867>[<font color="red">410</font>](#line-type-410) | 3 | | | 4868>[<font color="red">411</font>](#line-type-411) | 3 | | | 4869>[<font color="red">ACK:</font>](#line-type-ack) | 4 | | | 4870>[<font color="red">BLK:</font>](#line-type-blk) | 2 | Yes | Yes | <font color="red">+BLK:</font> 4871>[<font color="red">CALL:</font>](#line-type-call) | 2 | | | 4872 4873<br> 4874 4875> 4876>Line type | FS | History? | Modules? | Forwarded? 4877>:--------- |----|:--------:|:--------:|:---------- 4878>[<font color="red">CALLINFO:</font>](#line-type-callinfo) | 2 | | | 4879>[<font color="red">CID:</font>](#line-type-cid) | 1 | Yes | Yes | <font color="red">+CID:</font> 4880>[<font color="red">CIDINFO:</font>](#line-type-cidinfo) | 1 | Yes | Yes | <font color="red">+CIDINFO:</font> 4881>[<font color="red">END:</font>](#line-type-end) | 2 | Yes | | <font color="red">+END:</font> 4882>[<font color="red">GOODBYE</font> (client)](#line-type-goodbye-client) | 1 | | | 4883>[<font color="red">GOODBYE</font> (gateway)](#line-type-goodbye-gw) | 2 | | | 4884>[<font color="red">HELLO:</font> (client)](#line-type-hello-client) | 1 | | | 4885>[<font color="red">HELLO:</font> (gateway)](#line-type-hello-gw) | 2 | | | 4886>[<font color="red">HUP:</font>](#line-type-hup) | 1 | Yes | Yes | <font color="red">+HUP:</font> 4887>[<font color="red">INFO:</font>](#line-type-info) | 3 | | | 4888>[<font color="red">LOG:</font>](#line-type-log) | 1 | | | 4889>[<font color="red">MSG:</font> (client output)](#line-type-msg-client) | 1 | | | 4890>[<font color="red">MSG:</font> (gateway alerts)](#line-type-msg-gw-alerts) | 2 | Yes | Yes | <font color="red">+MSG:</font> 4891>[<font color="red">MSG:</font> (gateway output)](#line-type-msg-gw-output) | 2 | | | 4892>[<font color="red">MSG:</font> (server alerts)](#line-type-msg-server-alerts) | 1 | Yes | Yes | <font color="red">+MSG:</font> 4893>[<font color="red">MSG:</font> (server output)](#line-type-msg-server-output) | 1 | Yes | Yes | <font color="red">+MSG:</font> 4894>[<font color="red">MWI:</font>](#line-type-mwi) | 2 | Yes | Yes | <font color="red">+MWI:</font> 4895>[<font color="red">NOT:</font> (gateway)](#line-type-not-gateway) | 2 | Yes | Yes | <font color="red">+NOT:</font> 4896>[<font color="red">NOT:</font> (server)](#line-type-not-server) | 2 | Yes | Yes | <font color="red">+NOT:</font> 4897>[<font color="red">OPT:</font>](#line-type-opt) | 1 | | | 4898>[<font color="red">OUT:</font>](#line-type-out) | 2 | Yes | Yes | <font color="red">+OUT:</font> 4899>[<font color="red">PID:</font>](#line-type-pid) | 2 | Yes | Yes | <font color="red">+PID:</font> 4900>[<font color="red">PUT:</font>](#line-type-put) | 2 | Yes | Yes | <font color="red">+PUT:</font> 4901>[<font color="red">REQ:</font>](#line-type-req) | 3 | | | 4902>[<font color="red">REQ: ACK</font> (client)](#line-type-req-ack-client) | 4 | | | 4903 4904<br> 4905 4906> 4907>Line type | FS | History? | Modules? | Forwarded? 4908>:--------- |----|:--------:|:--------:|:---------- 4909>[<font color="red">REQ: ACK</font> (gateway)](#line-type-req-ack-gateway) | 4 | | | 4910>[<font color="red">REQ: DIAL</font> or <font color="red">DIAL_ABORT</font>](#line-type-req-dial)| 3 | | | 4911>[<font color="red">REQ: INFO</font>](#line-type-req-info) | 3 | | | 4912>[<font color="red">REQ: RELOAD</font>](#line-type-req-reload) | 3 | | | 4913>[<font color="red">REQ: REREAD</font>](#line-type-req-reread) | 3 | | | 4914>[<font color="red">REQ: UPDATE</font>](#line-type-update) | 3 | | | 4915>[<font color="red">REQ: UPDATES</font>](#line-type-updates) | 3 | | | 4916>[<font color="red">REQ: YO</font> (client)](#line-type-req-yo-client) | 4 | | | 4917>[<font color="red">REQ: YO</font> (gateway)](#line-type-req-yo-gateway) | 4 | | | 4918>[<font color="red">REQ: alias</font>](#line-type-req-alias) | 3 | | | 4919>[<font color="red">REQ: black</font>](#line-type-req-black) | 3 | | | 4920>[<font color="red">REQ: white</font>](#line-type-req-white) | 3 | | | 4921>[<font color="red">RESP:</font>](#line-type-resp) | 3 | | | 4922>[<font color="red">RID:</font>](#line-type-rid) | 2 | Yes | Yes | <font color="red">+RID:</font> 4923>[<font color="red">RPLY:</font>](#line-type-rply) | 3 | | | 4924>[<font color="red">RLY:</font> (Relay Job Origin (RJO))](#line-type-rly-rjo) | 5 | Yes | | <font color="red">+RLY:</font> 4925>[<font color="red">RLY:</font> (Relay Job Target (RJT))](#line-type-rly-rjt) | 5 | Yes | | <font color="red">+RLY:</font> 4926>[<font color="red">WID:</font>](#line-type-wid) | 2 | Yes | Yes | <font color="red">+WID:</font> 4927>[<font color="red">WRK:</font>](#line-type-wrk) | 3 | | | 4928>[<font color="red">WRK: ACCEPT LOG</font>](#line-type-wrk-accept-log) | 3 | | | 4929>[<font color="red">WRK: ACCEPT LOGS</font>](#line-type-wrk-accept-logs) | 3 | | | 4930>[<font color="red">WRK: REJECT LOG</font>](#line-type-wrk-reject-log) | 3 | | | 4931>[<font color="red">WRK: REJECT LOGS</font>](#line-type-wrk-reject-logs) | 3 | | | 4932 4933 4934<!-- 4935[## Appendix C: Quick Reference List of all server configuration settings] 4936--> 4937 4938## <a name="quick-ref-serv-config"></a> Appendix C: Quick Reference List of all server configuration settings 4939 4940> Arranged alphabetically by setting name. 4941> 4942 File Name |Setting name| Brief description 4943 ----------|------------|:-------------------------------------------------------- 4944 ncidd.conf| announce | file name of raw modem device (.rmd) file to be played 4945 ncidd.conf| audiofmt | "AT" command string to set voice modem audio format 4946 ncidd.conf| blacklist | blacklist file name 4947 ncidd.conf| cidalias | alias file name 4948 ncidd.conf| cidinput | select Caller ID source 4949 ncidd.conf| cidlog | log file name for call activity 4950 ncidd.conf| cidlogmax | maximum size in bytes of cidlog 4951 ncidd.conf| cidnoname | enable/disable detection of caller ID name from Telco 4952 ncidd.conf| datalog | log file name for raw data received from modems and gateways 4953 ncidd.conf| gencid | enable/disable reporting of generic caller ID 4954 ncidd.conf| hangup | disable/select hangup mode 4955 ncidd.conf| hupmode | Hangup Extension: disable/select hangup mode 4956 ncidd.conf| hupname | Hangup Extension: file name of external script/program 4957 ncidd.conf| huprmd | Hangup Extension: file name of raw modem device (.rmd) file to be played 4958 ncidd.conf| ignore1 | enable/disable leading 1 in US/Canada 4959 ncidd.conf| initcid | "AT" command string to enable modem's caller ID 4960 ncidd.conf| initstr | "AT" command string to initialize modem 4961 ncidd.conf| lineid | phone line identifier 4962 ncidd.conf| lockfile | full path to modem/serial device lock file 4963 ncidd.conf| pickup | enable/disable sending of "AT" command string to pickup phone line 4964 4965<br> 4966 4967> 4968 File Name |Setting name| Brief description 4969 ----------|------------|:-------------------------------------------------------- 4970 ncidd.conf| pidfile | full path to server's process id file, prevents multiple instances 4971 ncidd.conf| port | server's listening TCP/IP port number 4972 ncidd.conf| regex | enable/disable POSIX or Perl Compatible regular expressions for alias, blacklist and whitelist files 4973 ncidd.conf| send cidinfo| enable/disable sending of ring info to clients 4974 ncidd.conf| send cidlog| enable/disable sending of call log to clients 4975 ncidd.conf| ttyclocal | enable/disable hardware flow control for modem or serial device 4976 ncidd.conf| ttyport | modem or serial device port name 4977 ncidd.conf| ttyspeed | modem or serial device communication speed 4978 ncidd.conf| verbose | verbose level 4979 ncidd.conf| whitelist | blacklist file name 4980 4981<!-- 4982[## Appendix D: More info about modem MESG hexadecimal characters] 4983--> 4984 4985## <a name="modem-mesg-hex"></a> Appendix D: More info about modem MESG hexadecimal characters 4986 4987> When a modem that is configured to 4988 output [Formatted Caller ID](#fs1-modem2server-formatted-cid) instead 4989 receives something in the [raw MDMF parameter data](#fs1-modem2server-mdmf) 4990 that it does not understand, it will generate a MESG line of the 4991 unknown parameter block as a series of hexadecimal characters using 4992 ASCII text. This does not mean an error was detected, rather it is 4993 additional call detail provided by the telco that the modem doesn't 4994 know how to decode. 4995 4996> The NMBR label may be DDN\_NMBR (Dialable Directory Number) instead, 4997> depending on the country. 4998 4999> Example of an incoming call generated by British Telecom in the UK: 5000 5001>> 5002 RING 5003>> 5004 MESG = 110101 5005 DATE = 0511 5006 TIME = 1852 5007 NAME = JOHN DOE 5008 NMBR = 4075550000 or DDN_NMBR = 4075550000 5009>> 5010 RING 5011 5012 5013> The hexadecimal characters can be interpreted by going to 5014> the [British Telecom document index](http://www.sinet.bt.com/sinet/SINs/index.htm), 5015> accepting the copyright agreement and then selecting Suppliers' 5016> Information Notes (SIN) [#227](http://www.sinet.bt.com/sinet/SINs/pdf/227v3p7.pdf). 5017> Page 22 of 34 has the following info (field names relabeled for clarity): 5018 5019>> 5020 Field name | Hex byte | Meaning 5021 ---------------- | ---------| ------- 5022 Parameter Code | 11 | Call type 5023 Parameter Length | 01 | 1 byte 5024 Qualifier | 01 | Voice call 5025 5026> This indicates a normal call so the MESG line can be safely ignored. 5027 5028 5029> Example of a call from Bell Canada: 5030 5031>> 5032 RING 5033>> 5034 DATE = 0511 5035 TIME = 1852 5036 NAME = JOHN DOE 5037 NMBR = 4075550000 or DDN_NMBR = 4075550000 5038 MESG = 06014C 5039>> 5040 RING 5041 5042 5043> The hexadecimal characters can be interpreted using page 15 of 21 of 5044 the [Bell Interface Document (BID), BID-0001 (on the Wayback Machine)](https://web.archive.org/web/20080908040823/http://www.bell.cdn-telco.com/bid/BID-0001Multiple.pdf): 5045 5046>> 5047>> 5048 Field name | Hex byte | Meaning 5049 ---------------- | ---------| ------- 5050 Parameter Code | 06 | Call type 5051 Parameter Length | 01 | 1 byte 5052 Qualifier | 4C ("L") | Long distance call 5053 5054> It is unclear what determines the sequence that the MESG line is 5055 emitted by the modem. For British Telecom, modems seem to generate MESG 5056 before DATE and for Bell Canada telcos, modems seem to generate it 5057 after NMBR/DDN\_NMBR. 5058 5059> Additional info in 5060 this [UK Telecom Google Group post](https://groups.google.com/forum/#!msg/uk.telecom/GDX2MEfhCJE/pFS-ioIJJroJ). 5061 5062<!-- 5063[## Appendix E: SMS Relay Job sequence diagram] 5064--> 5065 5066## <a name="ncidpop-sms-relay"></a> Appendix E: SMS Relay Job sequence diagram (new in API 1.4) 5067 5068> Below is a sequence diagram showing how NCIDpop relays SMS to NCID Android. 5069 5070> The first two sequences show the use of <font color="red">NOT:</font> 5071 only. The third sequence shows how <font color="red">RLY:</font> 5072 was added to allow NCIDpop to "remotely" send SMS messages. 5073 5074>  5075 5076<!-- 5077[## API Version Change History] 5078--> 5079 5080## <a name="api-history-top"></a> API Version Change History 5081 5082> As new features are added they are marked **(New in API ?.?)** 5083 5084> As features are removed, they are marked **(Removed in API ?.?)** 5085 5086> The API version number is represented by ?.? 5087 5088<!-- 5089[### Release Summary] 5090--> 5091 5092> ### <a name="api-release-summary"></a> Release Summary 5093> 5094>> 5095 API Version |NCID Version| Feature Sets 5096 ----------- |:----------:| ------------- 5097 1.10 | 1.11 | 1 2 3 4 5 5098 1.9 | 1.10 | 1 2 3 4 5 5099 1.8 | 1.9 | 1 2 3 4 5 5100 1.7 | 1.8 | 1 2 3 4 5 5101 1.6 | 1.7 | 1 2 3 4 5 5102 1.5 | 1.6 | 1 2 3 4 5 5103 1.4 | 1.5 | 1 2 3 4 5 5104 1.3 | 1.4 | 1 2 3 4 5105 1.2 | 1.3 | 1 2 3 4 5106 1.1 | 1.1 | 1 2 3 4 5107 1.0 | 1.0 | 1 2 3 4 5108 5109<!-- 5110[### Version 1.10] 5111--> 5112 5113>### <a name="api-history-1.10"></a> Version 1.10 5114 5115>> #### General changes 5116>> 5117>>> - Feature sets supported: 1 2 3 4 5 5118 5119>>> - Released simultaneously with NCID 1.11. 5120 5121>> #### Feature Set 1: Modem and Device Support 5122>> 5123 5124>>> [Server Implementation](#fs1-server-impl) 5125>>> 5126 5127>>> - Added <font color="red">254 Start of call log</font> line. 5128 5129 5130<!-- 5131[### Version 1.9] 5132--> 5133 5134>### <a name="api-history-1.9"></a> Version 1.9 5135 5136>> #### General changes 5137>> 5138>>> - Feature sets supported: 1 2 3 4 5 5139 5140>>> - Released simultaneously with NCID 1.10. 5141 5142>> #### Feature Set 1: Modem and Device Support 5143>> 5144 5145>>> [Server Implementation](#fs1-server-impl) 5146>>> 5147 5148>>> - Changed description of hangup and when <font color="red">CID:</font> line is sent. 5149 5150>>>> [Server Output Lines](#fs1-server-output) 5151 5152>>>> - Added "-4 = (modem) automatic hangup complete" to the CIDINFO table. 5153 5154<!-- 5155[### Version 1.8] 5156--> 5157 5158>### <a name="api-history-1.8"></a> Version 1.8 5159 5160>> #### General changes 5161>> 5162>>> - Feature sets supported: 1 2 3 4 5 5163 5164>>> - Released simultaneously with NCID 1.9. 5165 5166>> #### Before you begin 5167 5168>>> [ABOUT CONFIGURATION OPTIONS FOR SERVER IMPLEMENTATIONS](#about-config) 5169 5170>>> - Added **XDMF Gateway settings** line to the table 5171 5172>> #### Feature Set 1: Modem and Device Support 5173 5174>>> [SERVER IMPLEMENTATION](#fs1-server-impl) 5175 5176>>>> [Server Output Lines](#fs1-server-output) 5177 5178>>>> - Added "-3 = (gateway) BUSY signal for incomplete call" to the CIDINFO table. 5179 5180>>>> [Modem-to-server](#fs1-modem2server) 5181 5182>>>> - Changed **Formatted Caller ID*** to [ASCII Format Caller ID](#fs1-modem2server-ascii-format-cid). 5183Removed references to the Comet. 5184 5185>>>> - Changed **Unformulated Caller ID*** to [XDMF ASCII Format Caller ID](#fs1-modem2server-ascii-hex-format-cid). 5186 5187>> #### Feature Set 2: Gateway Support 5188 5189>>> [SERVER IMPLEMENTATION](#fs2-server-impl) 5190 5191>>> - Added a <font color="red">CIDINFO:</font> line with <font color="red">BUSY</font> if the ring count is -3. 5192 5193>>> - Added [XDMF Input](#fs2-xdmf-input). 5194 5195>>>> - Added [Holtek HT9032D operation mode](#fs2-xdmf-input-ht9032-op-mode). 5196 5197<!-- 5198[### Version 1.7] 5199--> 5200 5201>### <a name="api-history-1.7"></a> Version 1.7 5202 5203>> #### General changes 5204>> 5205>>> - Feature sets supported: 1 2 3 4 5 5206 5207>>> - Released simultaneously with NCID 1.8. 5208 5209>>> - Changes made throughout for <font color="red">OPT: regex</font> 5210and **ncidd.conf::regex**. These now support a dash to accommodate the 5211new value of 2 (regex-2) for PCRE (Perl Compatible Regular Expressions). 5212POSIX expressions were already supported but are now designated by regex-1. 5213 5214>> #### [Call/Message Line Types, Categories and Structure (new in API 1.7)](#comm) 5215 5216>>> - [**New**](#comm) 5217 5218>> #### Feature Set 1: Modem and Device Support 5219>> 5220 5221>>> [Server Implementation -> Modem-to-Server](#fs1-modem2server) 5222>>> 5223 5224>>> - [Added new support for Unformatted Caller ID (SDMF, MDMF)](#fs1-modem2server-unformatted-cid). 5225 5226>> #### Feature Set 2: Gateway Support 5227>> 5228 5229>>> Server Implementation -> Server Output Lines 5230>>> 5231 5232>>> - [<font color="red">MWI:</font>](#line-type-mwi) added as new line 5233type for Message Waiting Indicator. 5234 5235>>> - [<font color="red">PUT:</font>](#line-type-put) added as new line 5236type for smartphone outgoing call. 5237 5238>>> - [<font color="red">RID:</font>](#line-type-rid) added as new line 5239type for ringback caller ID. 5240 5241>>> [Gateway Implementation -> Gateway-to-Server](#fs2-gw2server) 5242>>> 5243 5244>>> - [<font color="red">CALL:</font>](#line-type-call) added 5245<font color="red">PUT:</font>, <font color="red">MWI:</font>, 5246 5247 5248<!-- 5249[### Version 1.6] 5250--> 5251 5252>### <a name="api-history-1.6"></a> Version 1.6 5253 5254>> #### General changes 5255>> 5256>>> - Feature sets supported: 1 2 3 4 5 5257 5258>>> - Released simultaneously with NCID 1.7. 5259 5260>> #### Feature Set 1: Modem and Device Support 5261>> 5262 5263>>> [Server Implementation](#fs1-server-impl) 5264>>> 5265 5266>>> - Added new <font color="red">GOODBYE</font> line type. 5267 5268>>> [Server Implementation -> Server Output Lines -> <font color="red">OPT: LineIDS:</font>](#line-type-opt) 5269>>> 5270 5271>>> - [**New**](#line-type-opt) 5272 5273>>> [Server Implementation -> Server Output Lines -> <font color="red">RPLY:</font>](#line-type-rply) 5274>>> 5275 5276>>> - [**New**](#line-type-rply) 5277 5278>>>> [Server Implementation -> Optional Server Hangup Extension](#fs1-hangup-ext) 5279>>>> 5280 5281>>>> - Hangup extensions can return a hangup reason to the server. 5282 5283 5284>>> [Client Implementation](#fs1-client-impl) 5285 5286>>> - Revised recommended content for <font color="red">HELLO: IDENT:</font>. 5287 Removed unnecessary verbiage stating servers can display these lines. 5288 5289>>> - Added new <font color="red">GOODBYE</font> line type. 5290 5291>>> [Client Implementation -> Client-to-Server -> <font color="red">GOODBYE</font>](#line-type-goodbye-client) 5292>>> 5293 5294>>> - [**New**](#line-type-goodbye-client) 5295 5296>>> [Client Implementation -> Client-to-Server](#fs1-client2server) 5297>>> 5298 5299>>> - Added new <font color="red">HELLO: CMD: send_log</font> command. 5300 5301>>> [Client Implementation -> Optional Client-to-TiVo Display](#fs1-client2tivo) 5302>>> 5303 5304>>> - <font color="dimgray">(Removed in API 1.6)</font> 5305 5306>>> [Optional Server Extensions -> Optional Server Hangup Extension](#fs1-hangup-ext) 5307>>> 5308 5309>>> - Added MODE field pair to data passed to Hangup Server Extension. 5310 5311>>> - Data returned to ncidd now includes hupmode. 5312 5313>> #### Feature Set 2: Gateway Support 5314>> 5315 5316>>> [Gateway Implementation -> Gateway-to-Server -> <font color="red">GOODBYE</font>](#line-type-goodbye-gw) 5317>>> 5318 5319>>> - [**New**](#line-type-goodbye-gw) 5320 5321>> #### Feature Set 3: Client Job Support 5322>> 5323 5324>>> [Overview of Available Client Jobs](#fs3-overview) 5325>>> 5326 5327>>> - Added new <font color="red">REQ: DIAL</font> and 5328 <font color="red">REQ: DIAL_ABORT</font> line types. 5329 5330>>> [Client Implementation](#fs3-client-impl) 5331>>> 5332 5333>>> - Added "dial" to graphical NCID client features. 5334 5335>>> [Client Implementation -> Client-to-Server -> <font color="red">REQ: DIAL|DIAL_ABORT</font>](#line-type-req-dial) 5336>>> 5337 5338>>> - [**New**](#line-type-req-dial) 5339 5340>>> [Client Implementation -> Client-to-Server -> Requirements For Dial-a-number Client Job](#fs3-dial-req) 5341>>> 5342 5343>>> - [**New**](#fs3-dial-req) 5344 5345>>> [Client Job Examples](#fs3-examples) 5346>>> 5347 5348>>> - Added <font color="red">REQ: DIAL</font> to overview table. 5349 5350>>> - Added [<font color="red">REQ: DIAL</font>](#fs3-example-dial) example. 5351 5352>> #### [Appendix B: Index to all line type definitions](#index-line-types) 5353>> 5354 5355>> - Added new <font color="red">REQ: DIAL</font>, <font color="red">REQ: DIAL_ABORT</font>, 5356 <font color="red">GOODBYE</font> and <font color="red">RPLY</font> 5357 line types. Removed unnecessary syntax for <font color="red">REQ: INFO</font>. 5358 5359<!-- 5360[### Version 1.5] 5361--> 5362 5363>### <a name="api-history-1.5"></a> Version 1.5 5364 5365>> #### General changes 5366>> 5367>>> - Feature sets supported: 1 2 3 4 5 5368 5369>>> - Released simultaneously with NCID 1.6. 5370 5371>> #### Feature Set 1: Modem and Device Support 5372>> 5373 5374>>> [Server Implementation](#fs1-server-impl) 5375 5376>>> - Added line type <font color="red">HELLO:</font>. 5377 5378>>> [Client Implementation](#fs1-client-impl) 5379 5380>>> - Added definition for line type <font color="red">HELLO:</font>. 5381 5382>> #### Feature Set 2: Gateway Support 5383 5384>>> [Gateway Implementation](#fs2-gw-impl) 5385 5386>>> - Added line type <font color="red">HELLO:</font>. 5387 5388>>> [Client Implementation](#fs2-client-impl) 5389 5390>>> - Added line type <font color="red">HELLO:</font>. 5391 5392>>> [Optional Client-to-Module](#fs2-client2module) 5393 5394>>> - Added line type <font color="red">HELLO:</font>. 5395 5396<!-- 5397[### Version 1.4] 5398--> 5399 5400>### <a name="api-history-1.4"></a> Version 1.4 5401 5402>> #### General changes 5403>> 5404>>> - Feature sets supported: 1 2 3 4 5 5405 5406>>> - Released simultaneously with NCID 1.5. 5407 5408>>> - Added definitions for line types <font color="red">+BLK, +CID, 5409 +END, +HUP, +MSG, +NOT, +OUT, +PID, +RLY, +WID</font> and 5410 <font color="red">+CIDINFO</font>. 5411 These represent line types from a Forwarding Gateway. They are 5412 otherwise the same as the same line types without the leading "+". 5413 5414>> #### Before you begin 5415 5416>>> [General notes on DATE and TIME field data](#gen-datetime) 5417 5418>>> - Added note that <font color="red">RLY:</font> line types will not 5419>>> be checked for missing DATE and TIME fields because they are expected 5420>>> to be present. 5421 5422>> #### Feature Set 2: Gateway Support 5423 5424>>> [Forwarding Gateway (Server-to-Server) (new in API 1.4)](#fs2-fwdgw) 5425 5426>>> - [**New**](#fs2-fwdgw) 5427 5428>> #### [Feature Set 5: Relay Job Support](#fs5-relay-job-support) 5429 5430>>> - [**New**](#fs5-relay-job-support) 5431 5432>> #### [Appendix A: Quick Reference List of all call type line identifiers](#quick-ref-call-types) 5433 5434>>> - Added <font color="red">RLY:</font>. 5435 5436>> #### [Appendix B: Index to all line type definitions](#index-line-types) 5437 5438>>> - Added <font color="red">RLY:</font> and <font color="red">RLYLOG:</font>. 5439 5440>> #### [Appendix E: SMS Relay Job sequence diagram](#ncidpop-sms-relay) 5441 5442>>> - [**New**](#ncidpop-sms-relay) 5443 5444<!-- 5445[### Version 1.3] 5446--> 5447 5448>### <a name="api-history-1.3"></a> Version 1.3 5449 5450>> #### General changes 5451>> 5452>>> - Feature sets supported: 1 2 3 4 5453 5454>>> - Released simultaneously with NCID 1.4 5455 5456>> #### Feature Set 1: Modem and Device Support 5457>> 5458 5459>>> [Server Implementation -> Server Output Lines](#fs1-server-output) 5460>>> 5461 5462>>>> - All <font color="red">OPT:</font> lines output by 5463 the server are for informational and troubleshooting purposes 5464 only. Clients can optionally make use of them by giving the user a 5465 way to display them. Otherwise, clients are not required to display 5466 them, do not need to take any action on them and can safely ignore them. 5467 See [Feature Set 1 <font color="red">OPT:</font> definition](#line-type-opt) 5468 and [Feature Set 1: Client Implementation](#fs1-client-impl) for 5469 more information. 5470 5471>> 5472>>> [Client Implementation](#fs1-client-impl) 5473>>> 5474>>>> - All <font color="red">OPT:</font> lines output by 5475 the server are for informational and troubleshooting purposes 5476 only. Clients can optionally make use of them by giving the user a 5477 way to display them. Otherwise, clients are not required to display 5478 them, do not need to take any action on them and can safely ignore them. 5479 See [Feature Set 1 <font color="red">OPT:</font> definition](#line-type-opt) 5480 and [Feature Set 1: Client Implementation](#fs1-client-impl) for 5481 more information. 5482 5483>> #### Feature Set 2: Gateway Support 5484>> 5485>>> [Client Implementation](#fs2-client-impl) 5486>>> 5487>>>> - All <font color="red">OPT:</font> lines output by 5488 the server are for informational and troubleshooting purposes 5489 only. Clients can optionally make use of them by giving the user a 5490 way to display them. Otherwise, clients are not required to display 5491 them, do not need to take any action on them and can safely ignore them. 5492 See [Feature Set 1 <font color="red">OPT:</font> definition](#line-type-opt) 5493 and [Feature Set 1: Client Implementation](#fs1-client-impl) for 5494 more information. 5495 5496>> #### Feature Set 3: Client Job Support 5497>> 5498 5499>>> [Server Implementation](#fs3-server-impl) 5500 5501>>>> - reload the blacklist and whitelist files 5502>>>> 5503 <font color="dimgray">(Removed in API 1.3) <strike> if 5504 the **ncidd.conf::hangup** option is being used </strike> </font> 5505 5506>>> [Client Implementation](#fs3-client-impl) 5507>>> 5508 5509>>>> - All <font color="red">OPT:</font> lines output by 5510 the server are for informational and troubleshooting purposes 5511 only. Clients can optionally make use of them by giving the user a 5512 way to display them. Otherwise, clients are not required to display 5513 them, do not need to take any action on them and can safely ignore them. 5514 See [Feature Set 1 <font color="red">OPT:</font> definition](#line-type-opt) 5515 and [Feature Set 1: Client Implementation](#fs1-client-impl) for 5516 more information. 5517 5518 5519>>>> Graphical client description 5520 5521>>>> - <font color="dimgray">(Removed in API 1.3) <strike>only if the 5522 server sends <font color="red">OPT: hangup</font> will the user have 5523 an option to force the server to reload the blacklist/whitelist files 5524 </strike></font> 5525 5526<!-- 5527[### Version 1.2] 5528--> 5529 5530>### <a name="api-history-1.2"></a> Version 1.2 5531 5532>> #### General changes 5533>> 5534>>> - Feature sets supported: 1 2 3 4 5535 5536>>> - Released simultaneously with NCID 1.3 5537 5538>> #### Feature Set 1: Modem and Device Support 5539>> 5540 5541>>> [Server Implementation -> Server Output Lines](#fs1-server-output) 5542>>> 5543>>>> - **changed:** 5544 *NONAME* to *NO NAME* 5545 *NONUMBER* to *NO-NUMBER* 5546 *NOLINE* to *NO-LINE* 5547 5548>> 5549>>> [Client Implementation](#fs1-client-impl) 5550>>> 5551>>>> - Removed `OPT: ignore1` from <font color="red">OPT:</font> section. 5552 5553>>>>> Note: In API 1.3, `OPT: ignore1` was re-implemented for informational 5554>>>>> and troubleshooting purposes only. 5555 5556>> #### Feature Set 2: Gateway Support 5557>> 5558>>> [Server Implementation -> Server Output Lines](#fs2-server-output) 5559>>> 5560>>>> - **changed:** 5561 *NONAME* to *NO NAME* 5562 *NONUMBER* to *NO-NUMBER* 5563 *NOLINE* to *NO-LINE* 5564 *NOTYPE* to *-* 5565 5566 5567<!-- 5568[### Version 1.1] 5569--> 5570 5571>### <a name="api-history-1.1"></a> Version 1.1 5572 5573>> #### General changes 5574>> 5575>>> - Feature sets supported: 1 2 3 4 5576 5577>>> - Released simultaneously with NCID 1.1 5578 5579>> #### Feature Set 1: Modem and Device Support 5580>> 5581>>> [Server Implementation -> Optional TCI Device-to-Server](#fs1-tci2server) 5582 5583>>>> - [**New**](#fs1-tci2server) 5584 5585 5586>> #### Feature Set 3: Client Job Support 5587>> 5588 5589>>> [Client Implementation -> Client-to-Server](#fs3-client2server) 5590>>> 5591>>>> Graphical client description 5592 5593>>>> - <font color="dimgray">(Removed in API 1.1) <strike>only if the 5594 server sends <font color="red">OPT: hangup</font> will the user be 5595 able to edit the blacklist/whitelist entries</strike></font> 5596 5597>>>> Updated the following Client Jobs: 5598>>> 5599>>>> - <font color="red">REQ: black add</font> 5600>>>> - <font color="red">REQ: black remove </font> 5601>>>> - <font color="red">REQ: white add</font> 5602>>>> - <font color="red">REQ: white remove</font> 5603>>>> 5604>>> with the following: 5605>>> 5606>>>>> <font color="dimgray">(Removed in API 1.1) <strike> The server must have 5607 sent and the client must have received, 5608 <font color="red">OPT: hangup</font> to enable this Client Job.</strike></font> 5609 5610 5611<!-- 5612[### Version 1.0] 5613--> 5614 5615>### <a name="api-history-1.0"></a> Version 1.0 5616 5617>> - Feature sets supported: 1 2 3 4 5618 5619>> - Released simultaneously with NCID 1.0 5620 5621>> - New 5622 5623<!-- 5624[## Documentation Change History] 5625--> 5626 5627## <a name="doc-history-top"></a> Documentation Change History 5628 5629<!-- 5630[ Apr 26, 2019] 5631--> 5632 5633>### <a name="doc-history-2019-04-26"></a> Apr 26, 2019 5634 5635>> HTML formatting 5636 5637>>> small change to the HTML for improved appearance 5638 5639<!-- 5640[ Oct 6, 2018] 5641--> 5642 5643>### <a name="doc-history-2018-10-25"></a> Oct 25, 2018 5644 5645>> #### Feature Set 1: Modem and Device Support 5646 5647>>> [SERVER IMPLEMENTATION](#fs1-server-impl) 5648 5649>>> - Changed description of hangup and when <font color="red">CID:</font> line is sent. 5650 5651>>>> [Server Output Lines](#fs1-server-output) 5652 5653>>>> - Added "-4 = (modem) automatic hangup completed" to the CIDINFO table. 5654 5655>> #### [Appendix C: Quick Reference List of all server configuration settings](#quick-ref-serv-config) 5656 5657>>> - Removed cidnoname from table 5658 5659<!-- 5660[ August 17, 2018] 5661--> 5662 5663>### <a name="doc-history-2018-08-17"></a> August 17, 2018 5664 5665>> #### Before you begin 5666 5667>>> [ABOUT CONFIGURATION OPTIONS FOR SERVER IMPLEMENTATIONS](#about-config) 5668 5669>>> - Added **XDMF Gateway settings** line to the table 5670 5671>> #### Feature Set 1: Modem and Device Support 5672 5673>>> [SERVER IMPLEMENTATION](#fs1-server-impl) 5674 5675>>>> [Server Output Lines](#fs1-server-output) 5676 5677>>>> - Added "-3 = (gateway) BUSY signal for incomplete call" to the CIDINFO table. 5678 5679>>>> [Modem-to-server](#fs1-modem2server) 5680 5681>>>> - Changed **Formatted Caller ID*** to [ASCII Format Caller ID](#fs1-modem2server-ascii-format-cid). 5682Removed references to the Comet. 5683 5684>>>> - Changed **Unformulated Caller ID*** to [XDMF ASCII Format Caller ID](#fs1-modem2server-ascii-hex-format-cid). 5685 5686>> #### Feature Set 2: Gateway Support 5687 5688>>> [SERVER IMPLEMENTATION](#fs2-server-impl) 5689 5690>>> - Added a <font color="red">CIDINFO:</font> line with <font color="red">BUSY</font> if the ring count is -3. 5691 5692>>> - Added [XDMF Input](#fs2-xdmf-input). 5693 5694>>>> - Added [Holtek HT9032D operation mode](#fs2-xdmf-input-ht9032-op-mode). 5695 5696<!-- 5697[ May 31, 2018] 5698--> 5699 5700>### <a name="doc-history-2018-05-31"></a> May 31, 2018 5701 5702>> #### General changes 5703>> 5704 5705>>> - Wherever practical, lists of line types were changed to 5706<font color="red">{CALLTYPES}</font> or <font color="red">{MSGTYPES}</font>. 5707 5708>>> - Redundant copies of field pair tables were removed and replaced with 5709links to [{CALLTYPES} Category Structure](#comm-calltypes) 5710or [{MSGTYPES} Category Structure](#comm-msgtypes). 5711 5712>>> - Renamed all call-type links to be line-type links. 5713 5714>>> - All <font color="red">+XXX:</font> and <font color="red">XXXLOG:</font> 5715definitions were removed because it is redundant data and is not 5716of value. They have the same definitions as <font color="red">XXX:</font>. 5717 5718>>> - [Appendix B: Index to all line type definitions](#index-line-types) 5719doesn't need "new in API" notations. 5720 5721>> #### Before you begin 5722>> 5723 5724>>> [About Line Types and Field Pairs](#about-pairs) 5725>>> 5726 5727>>> - Renamed "About *Field Pairs* and *Line Types*" to "About *Line Types* 5728and *Field Pairs*". 5729 5730>>> - Swapped section order of "Field Pairs" and "Line Types" in order to 5731explain <font color="red">XXX</font> convention. 5732 5733>> #### Feature Set 1: Modem and Device Support 5734>> 5735 5736>>> [Server Implementation](#fs1-server-impl) 5737>>> 5738 5739>>> - Added **ncidd.conf::cidlogmax** to discussion about **ncidd.conf::send cidlog**. 5740 5741>>> - Added missing reference to Hangup Extensions. 5742 5743>>> Server Implementation -> Server Output Lines 5744>>> 5745 5746>>> - [<font color="red">CIDINFO:</font>](#line-type-cidinfo) Updated 5747ring count descriptions to more accurately describe the values. 5748 5749>>> - [<font color="red">HUP:</font>](#line-type-hup) Added missing 5750reference to Hangup Extensions. 5751 5752>>> - [<font color="red">LOG:</font>](#line-type-log) Updated with a more 5753realistic example. 5754 5755>>> - [<font color="red">MSG:</font>](#line-type-msg-server-alerts) Added 5756missing server alert definition. 5757 5758>>> [Server Implementation -> Modem-to-Server](#fs1-modem2server) 5759>>> 5760 5761>>> - Moved and improved wording describing when caller ID is sent by 5762telcos in different countries. 5763 5764>>> [Client Implementation](#fs1-client-impl) 5765>>> 5766 5767>>> - Moved <font color="red">XXXLOG:</font> lines to be prior to line 5768type 250. Added missing reference to <font color="red">LOG:</font>. 5769 5770>>> - Combined hangup and hangup-1 to the same table row. 5771 5772>> #### Feature Set 2: Gateway Support 5773>> 5774 5775>>> Server Implementation -> Server Output Lines 5776>>> 5777 5778>>> - [<font color="red">END:</font>](#line-type-end) updated to clarify 5779that CTYPE can only be IN or OUT. 5780 5781>>> - [<font color="red">PID:</font>](#line-type-pid) removed reference 5782to output module ncid-notify. 5783 5784>>> - [<font color="red">WID:</font>](#line-type-wid) cosmetic, moved 5785"(new in API 1.1)" to end of line. 5786 5787>>> [Gateway Implementation](#fs2-gw-impl) 5788>>> 5789 5790>>> - Clarified "CALL field" is "CALL<type> field". 5791 5792>>> - Simplified and shortened text explaining <font color="red">CALL:</font> 5793text line format. 5794 5795>>> - Fixed typo, <font color="red">NOT:</font> uses MTYPE and not TYPE. 5796 5797>>> Gateway Implementation -> Gateway-to-Server 5798>>> 5799 5800>>> - [<font color="red">CALL:</font>](#line-type-call) clarified use of 5801CALLtype when using IN, CID and PID. 5802 5803>>> - [<font color="red">CALLINFO:</font>](#line-type-callinfo) clarified 5804use of CALLtype when using IN, CID and PID. 5805 5806>>> - [<font color="red">MSG:</font>](#line-type-msg-gw-alerts) added 5807missing gateway alert definition. 5808 5809>>> Gateway Implementation -> Gateway-to-Server 5810>>> 5811 5812>>> - [<font color="red">CALLINFO:</font>](#line-type-callinfo) changed 5813'CALL<type>' to 'CALL<io>'. CALLio can only be IN or OUT. 5814 5815>>> - [<font color="red">MSG:</font>](#line-type-msg-gw-output) added 5816missing gateway output definition. 5817 5818>>> [Client Implementation](#fs2-client-impl) 5819>>> 5820 5821>>> - Consolidated individual LOG: lines to <font color="red">XXXLOG:</font>. 5822 5823>> #### Feature Set 3: Client Job Support 5824>> 5825 5826>>> [Client Implementation](#fs3-dial-client-impl) 5827>>> 5828 5829>>> - Fixed link for 555-01XX fictional numbers. 5830 5831>> #### [Feature Set 4: Acknowledgment Support](#fs4-ack-support) 5832>> 5833 5834>> - Clarified that this Feature Set applies to gateways as well as 5835clients. Removed some repetitive explanations. Sorted request lines 5836alphabetically within sections. Improved overall wording for clarity. 5837 5838>>> [Server Implementation -> Server Output Lines](#fs4-server-output) 5839>>> 5840 5841>>> - Fixed example by changing PID: to CALL:. 5842 5843>>> [Gateway Implementation -> Gateway-to-Server](#fs4-gw2server) 5844>>> 5845 5846>>> - Added missing definitions for <font color="red">REQ: ACK</font> 5847depending on whether it's for a gateway or client implementation. 5848 5849>> #### [Country Codes](#country-codes) 5850>> 5851 5852>> - Added FR. Sorted alphabetically on country name. Links turned into 5853clickable links instead of just text. 5854 5855>> #### [Appendix A: Copy-and-paste friendly {CALLTYPES} and {MSGTYPES}](#quick-ref-call-types) 5856>> 5857 5858>> - Appendix A renamed from "Quick Reference List of all call type line 5859identifiers" to "Copy-and-paste friendly {CALLTYPES} and {MSGTYPES}". 5860Removed types not likely to be used. Added <font color="red">MWI</font>, 5861<font color="red">PUT</font> and <font color="red">RID</font>. 5862 5863>> #### [Appendix B: Index of line type definitions](#index-line-types) 5864 5865>> - Appendex B renamed from "Index to all line type definitions" to 5866"Index of line type definitions". Converted to a table and added all 5867new columns. 5868 5869>> #### [Appendix D: More info about modem MESG hexadecimal characters](#modem-mesg-hex) 5870>> 5871 5872>> - Modem 'MESG' data string is MDMF. Fixed broken links to external 5873documents. 5874 5875<!-- 5876[ November 5, 2017] 5877--> 5878 5879>### <a name="doc-history-2017-11-05"></a> November 5, 2017 5880 5881>> #### General changes 5882>> 5883 5884>>> - There were several places where features or line types were listed under 5885 Feature Set 1 when they should have been listed under Feature Set 2 or 3. 5886 In particular, verbiage related to gateways in Feature Set 1 was moved to, 5887 or duplicated, to their rightful place in Feature Set 2. Links updated. 5888 5889>>> - "Smart phone" was changed to "smartphone". 5890 5891>>> - Changed API Version Change History and Documentation Change History 5892 sections to use fewer font sizes. This improves readability. 5893 5894>>> - Some colons were missing in <font color="red">ACK:</font> and 5895 <font color="red">REQ:</font> line references. 5896 5897>>> - Added new <font color="red">INFO: dial</font> line to all Client Job 5898 examples. 5899 5900>>> - Added new <font color="red">OPT: LineIDS:</font> to examples where appropriate. 5901 5902>> #### Before you begin 5903>> 5904 5905>>> [About End-of-line Terminators](#about-eol) 5906 5907>>> - [**New**](#about-eol) 5908 5909 5910>>> [Ensuring connectivity with the server](#connectivity) 5911>>> 5912 5913>>> - Clarified that the three methods to test connectivity are listed 5914in order of increasing robustness. 5915 5916>>> - <font color="red">REQ: YO</font> is supported in Feature Set 4 not 5917Feature Set 2. 5918 5919>> #### Feature Set 1: Modem and Device Support 5920>> 5921 5922>>> [Server Implementation -> Server Output Lines](#fs1-server-output) 5923>>> 5924 5925>>> - Call/line types now in alphabetical order, e.g., <font color="red">CIDINFO:</font> 5926 now before <font color="red">CIDLOG:</font>. 5927 5928>>> - <font color="red">MSG:</font> server definition: removed 5929 incorrect reference to "user generated message". 5930 5931>>> - [<font color="red">OPT:</font> definition](#line-type-opt): 5932 5933>>>> Clarified that unless otherwise noted, all <font color="red">OPT:</font> 5934 lines should be ignored. It is an exception if a client needs to use them. 5935 5936>>>> Expanded descriptions of existing <font color="red">OPT:</font> lines. 5937 5938 5939>>> Server Hangup Support 5940>>> 5941 5942>>>> [Alphabetical list of related server configuration options:](#fs1-hangup-server-config-options) 5943 5944>>>> - Added cidinput, removed nomodem and noserial. 5945 5946>>>> [Server Implementation -> Optional Server Hangup Extension](#fs1-hangup-ext) 5947>>>> 5948 5949>>>> - Clarified that other lines to STDOUT will be logged in ncidd.log. 5950 5951>>> [Client Implementation](#fs1-client-impl) 5952>>> 5953 5954>>> - Improved wording regarding <font color="red">xxxLOG:</font> lines. 5955 Added <font color="red">MSGLOG:</font>. 5956 5957>>> - Clarified that unless otherwise noted, all <font color="red">OPT:</font> 5958 lines should be ignored. It is an exception if a client needs to use them. 5959 5960>>> [Client Implementation -> Client-to-Server](#fs1-client2server) 5961>>> 5962 5963>>> - Moved </a><font color="red">HELLO:</font> definition from Client 5964 Implementation overview to Client-to-Server section. 5965 5966>>> - Slight rewording of <font color="red">HELLO: CMD: no_log</font> to 5967 improve reading flow for new <font color="red">HELLO: CMD: send_log</font> command. 5968 5969>>> - [<font color="red">MSG:</font> client definition](#line-type-msg-client): added example. 5970 5971 5972>> #### Feature Set 2: Gateway Support 5973>> 5974 5975>>> [Server Implementation -> Server Output Lines](#fs2-server-output) 5976>>> 5977 5978>>> - Renamed "Server-to-Gateway" to "Server Output Lines" because the lines will 5979 be received by clients as well as gateways. 5980 5981>>> - Call/line types now in alphabetical order, e.g., <font color="red">CIDINFO:</font> 5982 now before <font color="red">END:</font>. 5983 5984>>> [Client Implementation](#fs2-client-impl) 5985>>> 5986 5987>>> - Removed <font color="red">MSG:</font> and <font color="red">MSGLOG:</font> 5988 because they belong in Feature Set 1. 5989 5990>>> - Clarified that unless otherwise noted, all <font color="red">OPT:</font> 5991 lines should be ignored. It is an exception if a client needs to use them. 5992 5993>>> - Added missing <font color="red">MSGLOG:</font> 5994 5995>>> - Removed reference to Client Jobs as it is for Feature Set 3. 5996 5997>>> - <font color="red">xxxLOG:</font> list now in alphabetical order. 5998 5999>> #### Feature Set 3: Client Job Support 6000>> 6001 6002>>> [Overview of Available Client Jobs](#fs3-overview) 6003>>> 6004 6005>>> - The table briefly describing each Client Job command had been duplicated 6006 in the Overview of Available Client Jobs and Client Job Examples sections. 6007 The Overview now has a link to the table instead. 6008 6009>>> [Server Implementation](#fs3-server-impl) 6010>>> 6011 6012>>> - Removed summary of <font color="red">REQ:</font> and 6013 <font color="red">WRK:</font> requests. These are adequately 6014 documented elsewhere. 6015 6016>>> [Server Implementation -> Server Output Lines](#fs3-server-output) 6017>>> 6018 6019>>> - Made description more generic by removing reference to **ncidutil**. 6020 6021 6022>>> [Server Implementation -> Server Output Lines -> <font color="red">402</font>](#line-type-402) 6023>>> 6024 6025>>> - Made description more generic by removing reference to **ncidutil**. 6026 6027>>> [Server Implementation -> Server Output Lines -> <font color="red">INFO:</font>](#line-type-info) 6028 6029>>> - Added text label "Format 1" and "Format 2". Added <font color="red">401</font> 6030 and <font color="red">410</font> to Format 1. Removed duplicated Format 2 6031 <font color="red">INFO:</font> lines that are already listed under 6032 <font color="red">REQ: INFO</font>. 6033 6034>>> - A third <font color="red">INFO:</font> line has been added to indicate 6035 whether the server has been enabled to dial numbers with a locally attached modem. 6036 6037>>> [Server Implementation -> Server Output Lines -> <font color="red">RESP</font>](#line-type-resp) 6038>>> 6039 6040>>> - Made description more generic by removing reference to **ncidutil**. 6041 6042>>> [Client Implementation](#fs3-client-impl) 6043>>> 6044 6045>>> - Clarified that unless otherwise noted, all <font color="red">OPT:</font> 6046 lines should be ignored. It is an exception if a client needs to use them. 6047 6048>>> [Client Implementation -> Client-to-Server -> <font color="red">REQ: INFO</font>](#line-type-req-info)] 6049>>> 6050 6051>>> - Clarified which fields must have an exact match. 6052 6053>>> - A third <font color="red">INFO:</font> line has been added to 6054indicate whether the server has been enabled to dial numbers with a 6055locally attached modem. 6056 6057 6058>>> [Client Job Examples](#fs3-examples) 6059>>> 6060 6061>>> - Clarified difference beween client and server links. Added server 6062 response code to server links. 6063 6064>> #### [Feature Set 4: Acknowledgment Support](#fs4-ack-support) 6065>> 6066 6067>> - Changed <font color="red">YO</font> to be <font color="red">REQ: YO</font>. 6068 6069>>> [Gateway Implementation -> Gateway-to-Server](#fs4-gw2server) 6070>>> 6071 6072>>> - Line types now in alphabetical order, e.g., <font color="red">REQ: ACK</font> 6073 now before <font color="red">REQ: ACK</font>. 6074 6075>> #### [Appendix A: Quick Reference List of all call type line identifiers](#quick-ref-call-types) 6076>> 6077 6078>> - Call types beginning with '+' now have their own section in Feature Set 2. 6079 6080>> #### [Appendix B: Index to all line type definitions](#index-line-types) 6081>> 6082 6083>> - Call types beginning with '+' now have their own section in Feature Set 2. 6084 6085>> - Split out the <font color="red">HELLO:</font> line types based on feature set. 6086 6087>> - Added <font color="red">+MSG</font> link for forwarding gateway. 6088 6089>> #### [Appendix C: Quick Reference List of all server configuration settings](#quick-ref-serv-config) 6090>> 6091 6092>> - Added cidinput, removed nomodem and noserial. 6093 6094<!-- 6095[ November 6, 2016] 6096--> 6097 6098>### <a name="doc-history-2016-11-06"></a> November 6, 2016 6099 6100 6101>> #### [Sending a Text Message](#sending-messages) 6102 6103>>> - Added <font color="red">HELLO:</font> lines. 6104 6105>> #### [Appendix B: Index to all line type definitions](#index-line-types) 6106 6107>>> - Added line type <font color="red">HELLO:</font>. 6108 6109<!-- 6110[ September 30, 2016] 6111--> 6112 6113>### <a name="doc-history-2016-09-30"></a> September 30, 2016 6114 6115>> #### General changes 6116>> 6117 6118>>> - Changed fs3-job-support links to fs3-client-job support to distinguish 6119>>> them from the new fs5-relay-job-support links. 6120 6121>>> - Changed all references to the MESG\*<msg>\* field pair to be 6122>>> MESG\*<hexchars>\*. 6123 6124>>> - In all field pair tables, added "being sent to the server" to the 6125>>> description for \#\#\# and "being sent from the server" to the 6126>>> description for \*\*\*. 6127 6128 6129>> #### Before you begin 6130 6131>>> [About configuration options for server implementations](#about-config) 6132 6133>>> - Expanded list of configuration files. 6134 6135>>> - Changed example of **ncidd.conf::cidlias** to be the less confusing 6136>>> example of **ncidd.conf::lockfile**. 6137 6138>>> [About field pairs and line types](#about-pairs) 6139 6140>>> - Change description and examples in Field Pairs section to explain 6141>>> that the prefix for a first field pair is either \#\#\# to indicate 6142>>> the line is being sent to the server, or \*\*\* to indicate it is 6143>>> being sent from the server. 6144 6145>>> [General notes on NAME, NMBR, LINE and MESG field data](#gen-text) 6146 6147>>> - Expanded description for MESG field data. 6148 6149>> #### Feature Set 1: Modem and Device Support 6150>> 6151 6152>>> [Modem-to-Server](#fs1-modem2server) 6153 6154>>> - Clarified descriptions of MESG and DDN\_NMBR; changed NAME in example 6155>>> to be JOHN DOE. 6156 6157>>>> [Optional Server Hangup Extension](#fs1-hangup-ext) 6158 6159>>>> - Improved description of how Hangup Extension scripts work. 6160 6161>> #### [Appendix D: More info about modem MESG hexadecimal characters](#modem-mesg-hex) 6162 6163>>> - [**New**](#modem-mesg-hex) 6164 6165<!-- 6166[ July 23, 2016] 6167--> 6168 6169>### <a name="doc-history-2016-07-23"></a> July 23, 2016 6170 6171>> #### General changes 6172>> 6173 6174>>> - None. 6175 6176>> #### Feature Set 1: Modem and Device Support 6177>> 6178 6179>>> [Server Implementation](#fs1-server-impl) 6180 6181>>>> [Optional Server Hangup Extension](#fs1-hangup-ext) 6182 6183>>>> - [**New**](#fs1-hangup-ext) 6184 6185<!-- 6186[ May 7, 2016] 6187--> 6188 6189 6190>### <a name="doc-history-2016-05-07"></a> May 7, 2016 6191 6192>> #### General changes 6193>> 6194 6195>>> - Updates for API 1.3. 6196 6197>>> - API Version Change History -> Release Summary 6198 6199>>>> - [**New**](#api-release-summary) 6200 6201>>> - Several sections in API 1.2 were incorrectly marked "(new in API 1.2)" 6202 when in fact these were documentation changes only and not functional 6203 changes. These have been corrected. 6204 6205>>> - References to specific **ncidd.conf** setting names were changed to 6206 the convention **<configuration file name::setting name>** 6207 throughout the document. 6208 6209>>> - Formatting changes throughout to make rendering more compatible with 6210 the Haroopad markdown editor. 6211 6212>>> - References to hangup logic changed as appropriate to be "Internal 6213 Hangups" or "Hangup Extensions" to accommodate new Hangup Extensions. 6214 6215>>> - When Internal Hangups are enabled, <font color="red">OPT: hangup</font> 6216 lines will now have the format <font color="red">OPT: hangup-X</font> 6217 where "X" is the hangup mode in the range 1-3. Log file examples were 6218 changed throughout from <font color="red">OPT: hangup</font> to 6219 <font color="red">OPT: hangup-1</font>. 6220 6221>>> - When Hangup Extensions are enabled, the server will send 6222 <font color="red">OPT: hupmode-X</font> lines where "X" is the hangup 6223 mode in the range 1-3. 6224 6225>>> - Added "Released simultaneously with NCID..." to API Version 6226 history 1.0 to 1.3. 6227 6228>>> - Added text "Appendix A:" in front of "Quick Reference List of all 6229call type line identifiers". 6230 6231>>> - Added text "Appendix B:" in front of "Index to all line type definitions". 6232 6233>> #### Before you begin 6234 6235>>> [About configuration options for server implementations](#about-config) 6236 6237>>> - [**New**](#about-config) 6238 6239>> #### Feature Set 1: Modem and Device Support 6240>> 6241 6242>>> [Server Implementation](#fs1-server-impl) 6243 6244>>>> [Optional Server Extensions](#fs1-server-ext) 6245 6246>>>> - [**New**](#fs1-server-ext) 6247 6248>>>> [Optional Server Hangup Extension](#fs1-hangup-ext) 6249 6250>>>> - [**New**](#fs1-hangup-ext) 6251 6252>>> [Server Implementation -> Server Output Lines](#fs1-server-output) 6253>>> 6254 6255>>> - Clarified what "hangup" means for <font color="red">CIDINFO:</font> lines. 6256 6257>>> - Expanded description for <font color="red">OPT:</font> . 6258 6259>> #### Feature Set 2: Gateway Support 6260 6261>>> [Gateway Implementation](#fs2-gw-impl) 6262 6263>>> - Clarified what "hangup" means for <font color="red">CALL:</font> lines. 6264 6265>> #### Feature Set 3: Client Job Support 6266 6267>>> [Client Implementation](#fs3-client-impl) 6268 6269>>> - Improved wording on features that will probably be needed for a GUI 6270 client. 6271 6272>> #### API Version 1.2 History 6273 6274>>> Feature Set 3: Client Job Support -> Client Implementation 6275 6276>>> - Removed the <font color="red">OPT: hangup</font> requirement 6277>>> from the client section but not the server section. 6278 6279>>> Feature Set 3: Client Job Support -> Client-to-Server 6280 6281>>> - The reference to <font color="red">OPT: hangup</font> added in 6282 API Version 1.1 was removed. 6283 6284>> #### API Version 1.1 History 6285 6286>>> Feature Set 3: Client Job Support -> Client Job Output Lines 6287 6288>>> - Added these lines to indicate 6289>>> <font color="red">OPT: hangup</font> from the server was not 6290>>> required to edit the blacklist and whitelist files: 6291>>>> (Removed in API 1.1) 6292 The following require receiving <font color="red">OPT: hangup</font> from the server: 6293 6294>>> - Did not remove the <font color="red">OPT: hangup</font> 6295>>> requirement from the server and client implementation sections. 6296 6297>> #### Appendix C: Quick Reference List of all server configuration settings 6298 6299>>> - [**New**](#quick-ref-serv-config) 6300 6301<!-- 6302[ December 29, 2015] 6303--> 6304 6305>### <a name="doc-history-2015-12-29"></a> December 29, 2015 6306 6307>> #### General changes 6308>> 6309 6310>>> - Updates for API 1.2. 6311 6312>>> - NCID-API converted from OpenDocument Text (.odt) to Markdown (.md). 6313 6314>>> - Reworked formatting for all tables for better readability. 6315 6316>>> - All ambiguous references to <u>*line*</u> or <u>*label*</u> were 6317 changed to <u>*lineid*</u>. 6318 6319>>> - Where appropriate, tables defining <field label><field data> 6320 pairs for NAME, NMBR, LINE and MESG were changed to have a clickable 6321 link to the new 6322 [General notes on NAME, NMBR, LINE and MESG field data](#gen-text) 6323 section. 6324 6325>>> - Similarly, where appropriate, tables defining <field label><field data> 6326 pairs for DATE and TIME were changed to have a clickable link to the new 6327 [General notes on DATE and TIME field data](#gen-datetime) 6328 section. 6329 6330>>> - Section headings were renamed to more clearly indicate 6331their content. 6332 6333>>> Examples: 6334 6335>>>> 6336 Old | New 6337 -------------------------------------|----------------------- 6338 Modem input to the server |Modem-to-Server 6339 Gateway Output Lines |Gateway-to-Server 6340 6341>> #### Before you begin 6342 6343>>> About field pairs and line types 6344 6345>>> - [**New**](#about-pairs) 6346 6347>>> General notes on NAME, NMBR, LINE and MESG field data 6348 6349>>> - [**New**](#gen-text) 6350 6351>>> General notes on DATE and TIME field data 6352 6353>>> - [**New**](#gen-datetime) 6354 6355>>> Ensuring connectivity with the server 6356 6357>>> - [**New**](#connectivity) 6358 6359>>> Companion documents 6360 6361>>> - [**New**](#companion) 6362 6363>> #### Feature Set 1: Modem and Device Support 6364>> 6365>>> [Server Implementation](#fs1-server-impl) 6366>>> 6367 6368>>>> - Added <font color="red">\\n (newline)</font> section. 6369 6370>>> [Server Implementation -> Server Output Lines](#fs1-server-output) 6371>>> 6372 6373>>>> - Clarified that <font color="red">OPT:</font> options are always 6374 lowercase unless otherwise indicated. 6375 6376>>> [Server Implementation -> Server Alias Support](#fs1-alias-support) 6377>>> 6378>>>> - [**New**](#fs1-alias-support) 6379 6380>>> [Server Implementation -> Server Hangup Support](#fs1-hangup-support) 6381>>> 6382>>>> - [**New**](#fs1-hangup-support) 6383>>> 6384>>> [Client Implementation -> Client-to-Server](#fs1-client2server) 6385>>> 6386 6387>>>> - Added <font color="red">\\n (newline)</font> section. 6388 6389>> 6390>>> [Optional Client-to-Module](#fs1-client2module) 6391>>> 6392>>>> - Added standard input line 8 to have message type. 6393 6394>> #### Feature Set 3: Client Job Support 6395>> 6396>>> Feature Set 3 has been significantly enhanced with 6397 new content. 6398 6399>>> [Overview of Available Client Jobs](#fs3-overview) 6400>>> 6401>>>> - [**New**](#fs3-overview) 6402>> 6403 6404>> 6405>>> [Client Implementation -> Client-to-Server](#fs3-client2server) 6406>>> 6407>>>> - Added: Modifying an alias and specifying a new alias of nothing 6408 (null) is the same as removing an existing alias. 6409 6410>>>> - Added: <font color="red">REQ: alias remove</font> syntax 6411>> 6412 6413>>> [Server Implementation](#fs3-server-impl) 6414>>> 6415>>>> - Fixed typo in <font color="red">INFO: alias</font> section - 6416 NMBDEP was changed to NMBRDEP. 6417 6418>>> [Server Implementation -> Server Output Lines](#fs3-server-output) 6419>>> 6420>>>> - <font color="red">400: </font> section was clarified by adding 6421 the sentence: "Nothing is sent back to the server." 6422 6423>>>> - Added NOALIAS to <font color="red">INFO:</font> section. 6424 6425>>> [Client Job Examples](#fs3-examples) 6426>>> 6427>>>> - [**New**](#fs3-examples) 6428>> 6429 6430>> #### Appendix A: Quick Reference List of all call type line identifiers 6431 6432>>> - [**New**](#quick-ref-call-types) 6433 6434>> #### Appendix B: Index to all line type definitions 6435 6436>>> - [**New**](#index-line-types) 6437 6438<!-- Start of markdown editor specific formatting notes 6439 6440Bulleted items 6441============== 6442 6443ReText handles it OK, but Haroopad markdown editor doesn't render properly when 6444second and following bulleted items are indented with spaces. 6445 6446So instead of doing this which is OK in ReText: 6447 6448>> - item 6449 - item 6450 - item 6451 - item 6452 6453One has to do this in Haroopad: 6454 6455>> - set cidalias 6456- set ignore1 6457- set lineid 6458- set regex 6459 6460or this: 6461 6462>> - set cidalias 6463>> - set ignore1 6464>> - set lineid 6465>> - set regex 6466 6467End of markdown editor specific formatting notes--> 6468
