DEFINITION MODULE Domains;

        (********************************************************)
        (*                                                      *)
        (*        The local domains that Weasel is hosting      *)
        (*                                                      *)
        (*  Programmer:         P. Moylan                       *)
        (*  Started:            22 July 2002                    *)
        (*  Last edited:        23 September 2025               *)
        (*  Status:             OK                              *)
        (*                                                      *)
        (********************************************************)

FROM Names IMPORT
    (* type *)  UserName, PassString, HostName, DomainName, FilenameString;

FROM INIData IMPORT
    (* type *)  HINI;


CONST LockFileName = "LOCK.!!!";

TYPE Domain;          (* is private *)


PROCEDURE RefreshMasterDomainList(* (LogIt: BOOLEAN)*);

    (* Discards then re-creates the list of all domains, updates        *)
    (* the global variables MailRoot and RelayEverything, and updates   *)
    (* our list of IP addresses.  This procedure is to be called during *)
    (* initialisation, and subsequently whenever there is a chance that *)
    (* the INI data might have been updated.                            *)

PROCEDURE ClearMailboxLocks;

    (* Clears the POP lock in every mailbox, in case it was left set    *)
    (* by an improper shutdown.                                         *)

PROCEDURE SetPrincipalIPAddress (address: CARDINAL);

    (* Specifies which address is to be considered out principal IP     *)
    (* address, in case we have multiple interfaces.  If address = 0,   *)
    (* we allow the address to be calculated internally.                *)

PROCEDURE RefreshOurIPAddresses(): BOOLEAN;

    (* Updates the internal list of our local IP addresses.             *)
    (* Returns TRUE iff one of these is an active dial-up interface.    *)

PROCEDURE RecomputeLocalDomainNames (VAR (*OUT*) IPAddress: CARDINAL);

    (* This procedure is to be called when our host name or IP address  *)
    (* might have changed, e.g. because we've just come on-line.        *)
    (* Refreshes the master domain list, and returns the IP address     *)
    (* for our primary interface.                                       *)

PROCEDURE AddressIsLocal (IPAddress: CARDINAL): BOOLEAN;

    (* Returns TRUE if the argument is the IP address of an     *)
    (* interface on the local host.                             *)

PROCEDURE NameToDomain (VAR (*IN*) name: DomainName): Domain;

    (* Translates a domain name to a domain.  *)

PROCEDURE NameOfDomain (D: Domain;  VAR (*OUT*) name: DomainName);

    (* Returns the name of domain D in name. *)

PROCEDURE NameOfFirstDomain (VAR (*OUT*) name: DomainName);

    (* Returns the name of one of our domains. *)

PROCEDURE DomainIsLocal (VAR (*IN*) name: DomainName;
                         VAR (*OUT*) D: Domain): BOOLEAN;

    (* If name is one of our own domains, or an acceptable alias for    *)
    (* it, identifies the domain and returns TRUE.  We assume the       *)
    (* name is in lower case.                                           *)

PROCEDURE IsValidUsername (VAR (*IN*) name: ARRAY OF CHAR;  D: Domain): BOOLEAN;

    (* Returns TRUE iff this is the name of a mailbox in domain D.  We  *)
    (* assume that 'name' is already in lower case.  This merely does   *)
    (* a quick existence check, it does not load any user data.         *)

PROCEDURE SMTPAuthAllowed (VAR (*IN*) name: ARRAY OF CHAR;  D: Domain): BOOLEAN;

    (* Returns TRUE iff this user is allowed to authenticate SMTP       *)
    (* transactions using the AUTH command.                             *)

PROCEDURE LogPOPsessions (VAR (*IN*) name: ARRAY OF CHAR;  D: Domain): BOOLEAN;

    (* Returns TRUE iff we log POP sessions for this user, even when    *)
    (* POP logging is otherwise disabled.                               *)

PROCEDURE MailDirectoryFor (D: Domain;  VAR (*OUT*) DirName: FilenameString);

    (* Returns the 'mail root' directory for this domain. *)
    (* A trailing '\' is included in the result.          *)

PROCEDURE ShortMailDirectoryFor (D: Domain;  VAR (*OUT*) DirName: FilenameString);

    (* Like MailDirectoryFor, but the result is relative to MailRoot. *)

PROCEDURE OpenDomainINI (D: Domain): HINI;

    (* Opens the INI or TNI file for this domain, as appropriate. *)

PROCEDURE CloseDomainINI (D: Domain;  hini: HINI);

    (* Closes the INI or TNI file for this domain. *)

        (********************************************************)
        (*            MATCHING A USER TO A DOMAIN               *)
        (********************************************************)

TYPE DomainSearchState;    (* is private*)

PROCEDURE StartDomainSearch (VAR (*IN*) user: ARRAY OF CHAR;
                                   VAR (*IN*) domainstring: DomainName;
                                      IPaddr: CARDINAL): DomainSearchState;

    (* Sets up the initial state for a search.  The DomainSearchState   *)
    (* is set up in such a way that the search will find all domains    *)
    (* for which IPaddr is a valid address AND which have user as a     *)
    (* valid username.                                                  *)

PROCEDURE NextDomain (VAR (*INOUT*) state: DomainSearchState;
                              VAR (*OUT*) D: Domain;
                              VAR (*OUT*) password: PassString): BOOLEAN;

    (* Finds one domain, returns FALSE if we have run out of possibilities. *)

PROCEDURE EndDomainSearch (VAR (*INOUT*) state: DomainSearchState);

    (* Final tidying-up at the end of a search. *)

END Domains.

