North American Numbering Plan (NANP) specifics in ThemWi system sw
==================================================================

Themyscira Wireless system software, as currently written, is strongly tied to
NANP.  More precisely, it thoroughly assumes that all local phone numbers are
in +1 country code and follow NANP rules, and that all E.164 telephone numbers
in country codes other than +1 are foreign - numbers which we can call and
receive calls from, but which can never be local to us.

Why does our software need to have these assumptions baked into it, why can't
it be country-agnostic?  The present article answers this question, and this
long answer needs to be thoroughly understood before there can be any meaningful
discussion of how the software could possibly be adapted to other countries and
their respective telephone numbering plans.

In principle, there exists a standardized dialing format on all GSM phones that
remains the same no matter which country you happen to be in.  If you always
enter phone numbers (dialing, SMS manual entry, phone book entries) in full
international format beginning with the '+' symbol (press and hold the '0'
button before the number in most phone UIs), the phone handset firmware will
capture the number with TON=1, NPI=1 attributes (signifying international number
format in GSM call control and SMS protocols) and transmit it as such to the
GSM network.  Every properly designed GSM network, upon seeing a number with
these TON=1, NPI=1 attributes, must address the call or message to the country
indicated by the country code at the beginning of the full E.164 number, whether
that country is your local one or some other.  Thus if everyone were to always
use only full E.164 numbers in full international format, network software could
hypothetically be written in a country-agnostic way, treating full E.164 phone
numbers as opaque strings without parsing.  However, there are two practical
problems with such country-agnostic approach:

1) Most human users of mobile phones dial local phone numbers (within their own
   country) in a way that follows local dialing conventions, rather than in
   international format beginning with '+' and their own country code.  For
   example, in USA a given 10-digit NANP phone number can be dialed as just the
   10 digits NPANXXXXXX, as 11-digit 1NPANXXXXXX, or as full international
   +1NPANXXXXXX - and a proper cellphone network MUST accept all 3 formats as
   equivalent.

2) As explained further in this article, a network implementation must be able
   to look at a telephone number and immediately tell if that number is locally
   owned ("one of ours") or belongs somewhere outside of the local GSM network.
   Practical implementation of this distinction requires a database of locally
   owned phone numbers, and the implementation of that database in turn becomes
   much easier when the local numbering plan is known and fixed.

Supported dialing formats in ThemWi
===================================

When themwi-mncc processes a mobile-originated (MO) call from a GSM subscriber,
it supports dialing the following classes of numbers:

* NANP numbers in any of the 3 standard dialing formats;

* International numbers in any country - an international number beginning
  with +1 is enforced to be valid NANP, but E.164 numbers in all other country
  codes are accepted as-is;

* Local 4-digit numbers described in (to-be-written) Local-short-numbers
  article;

* Whatever special numbers are configured in themwi-sip-out, such as 511 and
  911.

Only NANP numbers and specially configured 4-digit numbers (see
Local-short-numbers) can be local - all E.164 numbers in non-NANP country codes
are sent to the outbound call gateway, and all other unrecognized number formats
are likewise sent to themwi-sip-out so that the latter process can catch and map
special numbers like 511, 911 etc.

If a dialed number is recognized as NANP, themwi-mncc looks in the database of
locally owned numbers to see if the dialed number is one of ours - and the
outcome of this look-up determines if the call is handled locally or sent to
the outside world via themwi-sip-out.

No 7-digit dialing support
==========================

In the olden days of land lines, most localities in USA supported 7-digit
dialing: to call Jenny, you would merely dial her local 7-digit number 867-5309,
without needing to dial the local area code; full 10-digit numbers (or 11 digits
with leading '1') had to be dialed only when calling someone in a different
area code from your own.  However, this 7-digit dialing has now been disabled
even for land lines in most localities, including the locality where ThemWi
currently operates: per official rules, 7-digit dialing gets disabled (full
10-digit numbers become mandatory) whenever an area code overlay is implemented,
such as overlay of 760 and 442 area codes in our locality.

In the case of mobile phones, 7-digit dialing never made much sense to begin
with: if you dial only 7 digits, should the implicit area code be taken from
your own number, or should it be the area code of the locality you happen to be
traveling through at the moment?  The latter option is impossible in the case
of localities with two or more overlaid NPA codes, and it appears that official
rules once again call for simply disabling 7-digit dialing.

Based on these considerations, ThemWi system sw was written from the outset to
not support 7-digit dialing - it is no longer relevant in the current state of
telecom culture in USA.  We do, however. provide optional support for
abbreviated 4-digit local numbers - see (to-be-written) Local-short-numbers
article.

Database of locally owned numbers
=================================

The telecom culture in USA features full number portability - end users can take
their phone numbers with them anywhere, from one telecom provider to another,
and with mobile phones and VoIP services, from one geographic locality to any
other, making the entire country effectively "flat" for local/non-local
distinction purposes.  Therefore, the set of phone numbers "owned" (or rented
in reality) by a small network operator such as Themyscira Wireless does not
constitute any kind of clean-cut digit range partition in the numbering plan -
instead we can have a small set of locally owned numbers (say, on the order of
5 to 20 individual numbers), and each of these locally owned numbers can fall
anywhere in the whole nationwide 10-digit numbering plan.  So how can we tell,
by looking at an arbitrary NANP number, whether it is "one of ours" or not?

The implemented solution is an explicitly maintained database of locally owned
phone numbers, described in detail in (to-be-written) Number-database article.
The format of this database (the way numbers are entered, the way the input
format is parsed, and the compiled binary format used for fast look-ups) is
specific to NANP - only NANP numbers can be local in the present design.

Porting to other national telephone numbering plans
===================================================

If someone wishes to port ThemWi system sw for use in other countries with
respective local phone numbers, the following aspects will need to be changed:

* Based on the structure of your country's national numbering plan, you will
  need to come up with an appropriate local number database format for your
  country, or if the range of numbers belonging to your GSM network forms a
  clean-cut digit range partition, implement that scheme instead.

* You will need to modify MO call handling to recognize your country code
  (rather than +1) as the one calling for parsing and closer scrutiny of the
  dialed number, determining if it is local or not.

* Handling of non-international dialing formats (numbers dialed without '+')
  will need to be changed to whatever is appropriate for your country's telecom
  culture and customs.

* Handle all secondary fallout (throughout the code base) from the previous
  essential and necessary changes.

Using fake NANP numbers
=======================

If someone outside of North America wishes to merely play with ThemWi system sw
on a casual basis, without actually interconnecting to your non-USA PSTN with
non-NANP real phone numbers, the easiest way to bring the software up is to use
fake NANP numbers.  There are two types of guaranteed-fake (can't collide with
real ones) phone numbers in NANP:

1) NPA-555-01XX, where NPA is some real area code for some (any) actual locality
   in USA and XX can be any two digits.  This number range is specifically set
   aside for use in movies etc, with realistic USA settings - the area code can
   be any real one, but 555-01XX numbers are reserved for fake use in every
   area code.

2) Fake area codes of form N9X (290-299, 390-399, ..., 990-999) are also good
   for guaranteed-fake numbers as the middle digit of NPA is not allowed to be
   '9' per official NANP rules.  This method allows large ranges of fake NANP
   numbers.

See Fake-NANP-numbers article (to be written) for more info.