DialingCountry

AcceptEdit CheckPhoneNumberAndRememberDefaults IncludeOrOmitNationalAccessCode IsSpecialAreaCode IsSpecialNumber RemoveIgnorables

SharesCountryCode ShouldNormalizePhoneNumber StartsWithEmergencyNumber SuggestedPhoneNumberText ValidAreaCode

Attributes

CanDelete CanHaveMultipleOutsideLineCodes CountryCode HasAreaCodes HasLocalTolls HomeCountryDirectCode ISO3166CountryCode InternationalAccessCode

IsBuiltIn LastAreaCodeDialed MaximumAreaCodeLength MaximumDomesticNumberLength MaximumLocalNumberLength MinimumAreaCodeLength MinimumDomesticNumberLength MinimumLocalNumberLength

MustDialAreaCode NationalAccessCode NationalAccessConsideredSeparateFromAreaCode PhoneNumberFormatter PreferredDialingMethod PreferredDialingSpeed ValidFromDate

Fields

instance DialingCountry tag;
       sortText: nilObject;
    countryCode: nilObject;
    accessCodes: nilObject;
lastAreaCodeDialed: nilObject;
phoneNumberFormatter: nilObject;
lettersToPhoneDigitsMapping: nilObject;
 specialNumbers: nilObject;
emergencyNumbers: nilObject;
specialAreaCodes: nilObject;
  validFromDate: 0;
preferredDialingMethod: 0;
preferredDialingSpeed: 0;
minimumAreaCodeLength: 0;
maximumAreaCodeLength: 0;
minimumLocalNumberLength: 0;
maximumLocalNumberLength: 0;
minimumDomesticNumberLength: 0;
maximumDomesticNumberLength: 0;
      isBuiltIn: false;
mustDialAreaCode: false;
   hasAreaCodes: false;
  hasLocalTolls: false;
canHaveMultipleOutsideLineCodes: false;
nationalAccessConsideredSeparateFromAreaCode: false;
end instance;

Define Class DialingCountry;
    inherits from Object, EditAttributeClient, HasSortText, HasCountryCode;

    field countryCode:                  Text, getter;
    field accessCodes:                  Text;
        // Newline-separated access codes: 
        //      international\nnational\nhome country direct\nISO3166 country code
        //
        //  international: prefix for dialing other countries
        //  
        //  national: prefix for dialing domestic long distance calls and
        //      calls to countries that share the same country code.
        //
        // Example for US:
        //      text: '011\n1\n\n\nUS\n';
        //
        // Example for Japan (with AT&T USA Direct):
        //      text: '001\n0\n0039-111\nJP\n'
        //
        // Use the individual attributes InternationalAccessCode, NationalAccessCode,
        // HomeCountryDirectCode and ISO3166CountryCode for access.

    field lastAreaCodeDialed:           Text, getter;

    field phoneNumberFormatter:         PhoneNumberFormatter, getter, setter;
    field lettersToPhoneDigitsMapping:  ShortIntegerList;
    field specialNumbers:               Text;
    field emergencyNumbers:             Text;
    field specialAreaCodes:             Text;
    field validFromDate:                Signed, getter;

    field preferredDialingMethod:       UnsignedShort, getter, setter;
    field preferredDialingSpeed:        UnsignedShort, getter, setter;

    // Note: length fields are used for checking the validity
    // of a user-entered phone number.

    field minimumAreaCodeLength:        UnsignedByte, getter, setter;
    field maximumAreaCodeLength:        UnsignedByte, getter, setter;
    field minimumLocalNumberLength:     UnsignedByte, getter, setter;
    field maximumLocalNumberLength:     UnsignedByte, getter, setter;
    field minimumDomesticNumberLength:  UnsignedByte, getter, setter;
    field maximumDomesticNumberLength:  UnsignedByte, getter, setter;

    field isBuiltIn:                    Boolean, getter;
    field mustDialAreaCode:             Boolean, getter, setter;
    field hasAreaCodes:                 Boolean, getter, setter;
    field hasLocalTolls:                Boolean, getter, setter;
    field canHaveMultipleOutsideLineCodes:  Boolean, getter, setter;
    field nationalAccessConsideredSeparateFromAreaCode: Boolean, getter, setter;

    attribute PhoneNumberFormatter: PhoneNumberFormatter;
    
    overrides AcceptEdit;
        // make sure iDialingCountries updates to show new country name

    overrides CanDelete;
        // returns false for built-in system DialingCountries

    attribute CountryCode: Text;
        // SetCountryCode adds the oldCountry to iChangedDialingCountries so we
        // can later fix telenumbers that still refer to it.

    attribute HasAreaCodes: Boolean;
        // True if this country uses area codes or city codes.  Even countries
        // that use area codes may have some special phone numbers without area
        // codes.  For example, local toll free "950" numbers in the US, and
        // emergency numbers in most countries do not have area codes even
        // though their country normally does use area codes.
        //
        // When a DialingLocation object's dialingCountry changes, its
        // HasAreaCode attribute will be set to the HasAreaCode of the new
        // dialingCountry.
    
    attribute HasLocalTolls: Boolean;
    attribute CanHaveMultipleOutsideLineCodes: Boolean;
    
    attribute HomeCountryDirectCode: Text;
        // returns text object with the code to dial directly to the home
        // country of the device, using the home country's direct dial service
        // if it exists.

    attribute InternationalAccessCode: Text, safe;
        // Default prefix for dialing to another country.  The default is copied
        // into new DialingLocations, which the user can edit, thereby switching
        // to a different international carrier.  Examples: US->'011',
        // Japan->'001'.

    operation SuggestedPhoneNumberText(): Text;
        // called when a new empty phone number is being edited
        // returns the area code and/or national access code when appropriate
        // override rarely
    operation CheckPhoneNumberAndRememberDefaults(attribute: OperationNumber; domesticNumber: Text): Boolean;
        // called when a phone number is edited to update the default dialing country or area code
        // it always sets iDefaultDialingCountry to self
        // if <attribute> is operation_DialingCountry, it always returns true
        // if <attribute> is operation_Telephone, then it cleans up the phone number
        // and stores the cleaned phone number in <domesticNumber>, stores the
        // default area code and returns true if the phone number is valid for self
        // override rarely
    operation IncludeOrOmitNationalAccessCode(areaCodeText: HasText; includeIt: Boolean): Signed, noFail;
        // If includeIt is true, inserts the NationalAccessCode into in
        // areaCodeText if it is not already there.  If includeIt is false,
        // removes the NationalAccessCode from the beginning of areaCodeText if
        // it is there and it is not the only text in areaCodeText.  Either case
        // will work correctly when non-digits exists before the NationalAccessCode,
        // as in "(03) 1234-5678".
        //
        // Doesn't change special numbers or numbers containing quote or phone
        // control characters.
        //
        // Returns the number of digits added (negative if digits were removed).

    attribute LastAreaCodeDialed: Text;
        // auto-getter returns epehemeral copy of last area code dialed
        // setter strips ignorable characters before storing
    
    attribute MinimumAreaCodeLength:    UnsignedByte;
    attribute MaximumAreaCodeLength:    UnsignedByte;
        // Minimum and maximum number of digits in a correctly formed area/city
        // code for this country.  Both return zero for countries that do not
        // use area/city codes or whose area code length is unknown.

    attribute MinimumLocalNumberLength:     UnsignedByte;
    attribute MaximumLocalNumberLength:     UnsignedByte;
        // Minimum and maximum number of digits of a correctly formed
        // local phone number (does not include area code or national
        // access code) for this country.  Special numbers that are
        // built-in may have fewer digits than MinimumLocalNumberLength.

    attribute MinimumDomesticNumberLength:  UnsignedByte;
        // The minimum number of digits allowed in a domestic phone number.
        // Does not include the national access code.
        // Is usually zero (let area code and local number limits take care of things).
        // Is nonzero when we know that a country requires a domestic number to be at
        // least a certain number of digits.
    attribute MaximumDomesticNumberLength:  UnsignedByte;
        // the maximum number of digits allowed in a domestic phone number
        // does not include the national access code

    attribute IsBuiltIn: Boolean, readOnly;
        // returns true for DialingCountries that are built-in to the system
        // and cannot be deleted.

    operation SharesCountryCode(otherCountry: DialingCountry): Boolean;
        // Returns true if otherCountry shares the same country code as self.
        // Calls between such countries are considered domestic calls.

    operation IsSpecialNumber(number: Text): Boolean;
        // True if number is a special non-conforming number (like information, international operator, etc.)

    operation StartsWithEmergencyNumber(number: Text): Boolean;
        // true if number is a special non-conforming number that you want the user to confirm before dialing (like emergency, police, fire, etc.)

    operation IsSpecialAreaCode(areaCode: Text): Boolean;
        // True if areaCode is special and cannot be dialed from overseas or
        // with calling cards.

    attribute ISO3166CountryCode: Text;

    // Note: for the purposes of the following methods, the "area code" includes the
    // national access number only if NationalAccessConsideredSeparateFromAreaCode
    // is false.

    attribute MustDialAreaCode: Boolean;
        // True if the area/city code should always be dialed in this country
        // for domestic calls.  In some countries (like Japan), the caller must
        // include the city/area code even when dialing within the same
        // city/area code in some cases, but can omit it in other cases.  Always
        // dialing the city/area code is allowed and adds no expense to the
        // caller.
        //
        // When a DialingLocation object's dialingCountry changes, its
        // MustDialAreaCode will be set to the MustDialAreaCode of the new
        // dialingCountry.

    attribute NationalAccessCode: Text, safe;
        // Prefix for dialing long distance within this country (or to a country
        // that shares the same country code).  In the US, this is '1', in Japan
        // and most other countries, it is '0'.  The user can modify this value
        // in the dialing location scene, effectively switching to a different
        // local carrier.

    attribute NationalAccessConsideredSeparateFromAreaCode: Boolean;
        // True if inhabitants consider the nationalAccess (domestic long
        // distance code) to be separate from the area/city code.  For
        // example, U.S. residents consider the '1' in '1 (408) 774-4000' to
        // be a separate entity from the 408 area code.  Citizens from many
        // countries like Japan, Germany, and France think of the access code
        // (usually '0') and the area/city code to be a single unit.  Note
        // that it is still important for Magic Cap to distinguish between
        // nationalAccess and domestic area codes, since the nationalAccess
        // prefix is dropped when dialing from overseas.

    attribute PreferredDialingMethod: UnsignedShort;
        // When a DialingLocation object is created or when its dialingCountry
        // changes, its DialingMethod attribute will be set to the
        // PreferredDialingMethod of the new dialingCountry.  Values are
        // defined in Utilities.h

    attribute PreferredDialingSpeed: UnsignedShort;
        // When a DialingLocation object is created or when its dialingCountry
        // changes, its DialingSpeed attribute will be set to the
        // PreferredDialingSpeed of the new dialingCountry.  Values are
        // defined in Utilities.h

    operation ShouldNormalizePhoneNumber(domesticNumber: HasText): Boolean, noFail;
        // True if we should try and normalize domesticNumber.  If the number is
        // quoted, special, or contains non-digit and non-formatting characters
        // then ShouldNormalizePhoneNumber returns false.   If this country does
        // not have any formatting rules, ShouldNormalizePhoneNumber also
        // returns false.

    operation ValidAreaCode(areaCode: HasText): Boolean;
        // Test whether an area code is valid for this DialingLocation.

    attribute ValidFromDate: Signed, readOnly;
        // Date from which this DialingCountry is valid.  0 if unknown or
        // irrelevant.  All built-in DialingCountry instances use 0.

    operation RemoveIgnorables(number: HasText): Text;
        // uses the country's phone number formatter to remove ignorable characters from the phone number
        // returns an ephemeral text object
end class;