Software and Services, Portable Libraries  2019.Mar.01
A library for managing digital certificates
SoftwareAndServices::Library::UPN::UpnDB Class Reference

UPN (user) database objects. More...

#include <SaS/UpnDb/UpnDB.hpp>

+ Inheritance diagram for SoftwareAndServices::Library::UPN::UpnDB:
+ Collaboration diagram for SoftwareAndServices::Library::UPN::UpnDB:

Classes

class  Realm
 An object that contains a realm and all sub realms, in an ordered tree. More...
 

Public Member Functions

 UpnDB ()
 UpnDB - default Constructor. More...
 
virtual ~UpnDB ()
 UpnDB - destructor. More...
 
UpnDbAddressId_t AddAddress (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, UpnDbResourceId_t addressType, const String &street1, const String &street2, const String &city, const String &state, const String &zip, const String &country)
 Add address information for a UPN. More...
 
UpnDbAddressId_t AddAddress (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t UpnId, UpnDbResourceId_t AddressType, const String &Street1, const String &Street2, const String &City, const String &State, const String &Zip, UpnDbCountryCodeId_t Country)
 Add address information for a UPN. More...
 
UpnDbCcId_t AddCc (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, UpnDbAddressId_t addrId, const String &number, unsigned char expireMonth, unsigned short expireYear, const String &back, const char type, const String &cardHoldersName)
 Add credit card information for upnId. More...
 
UpnDbEmailId_t AddEmail (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, UpnDbResourceId_t ResourceType, const String &Email, const String &Name)
 Add email information for a UPN. More...
 
UpnDbMembershipId_t AddMembership (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realm, const String &name)
 Create a new membership list. More...
 
UpnDbPrefId_t AddPref (UpnDbAuthHandle_t AppAuth, UpnDbAuthHandle_t UpnAuth, const char *PrefKey, UpnDbPrefValueTypeId_t PrefType, const char *PrefValue, unsigned int Index=0)
 Add a new user preference. More...
 
UpnDbRealmId_t AddRealm (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t ParentRealm, const String &NewRealm, const String &Description, bool CanHaveChild=true, bool CanHaveUpns=true, bool CanRemove=true, bool Disabled=false)
 Add realm. More...
 
UpnDbRealmId_t AddRealm (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t ParentRealm, const char *NewRealm, const char *Description, bool CanHaveChild=true, bool CanHaveUpns=true, bool CanRemove=true, bool Disabled=false)
 Add realm. More...
 
bool AddRealmAdmin (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realm, UpnDbUpnId_t upnId)
 Make an existing UPN a realm administrator. More...
 
UpnDbResourceId_t AddResourceId (UpnDbAuthHandle_t AuthHandle, UpnDbResourceId_t System, const char *Name)
 Add a new resource name. More...
 
bool AddUpnToList (UpnDbAuthHandle_t AuthHandle, UpnDbMembershipId_t list, UpnDbUpnId_t upn, const String &expire)
 Add UPN to realms membership list. More...
 
UpnDbAuthHandle_t AppLogin (const String &GUID, const String &password, const String &appGUID, const String &appPassword, const String &host, const String &db)
 This is used by an application to find if it has access to UpnDB. More...
 
UpnDbAuthHandle_t AppLogin (const char *GUID, const char *password, const char *appGUID, const char *appPassword, const char *host, const char *db)
 This is used by an application to find if it has access to UpnDB. More...
 
UpnDbAuthHandle_t Authenticate (X509_STORE_CTX *Store, const char *const Upn, const char *const Realm, const char *const RemoteHost=nullptr, int16_t RemotePort=0)
 Authenticate a secure connection. More...
 
UpnDbAuthHandle_t Authenticate (UpnDbRealmId_t realm, const String &upn, const String &pw)
 Authenticate UPN. More...
 
UpnDbAuthHandle_t Authenticate (UpnDbRealmId_t realm, const char *upn, const char *pw)
 Authenticate UPN. More...
 
bool CanHaveChildren (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t RealmId)
 Find out if the named realm can have child realms. More...
 
bool ChargeCc (UpnDbAuthHandle_t AuthHandle, UpnDbCcId_t cc, const String &partNumber, const String &description, const String &amount)
 Charge a credit card. More...
 
bool ChargeCcMonthly (UpnDbAuthHandle_t AuthHandle, UpnDbCcId_t cc, const String &partNumber, const String &description, const String &amount)
 Charge a credit card monthly. More...
 
bool ChargeCcYearly (UpnDbAuthHandle_t AuthHandle, UpnDbCcId_t cc, const String &partNumber, const String &description, const String &amount)
 Charge a credit card yearly. More...
 
bool Connect (const String &host, const String &dbName, const String &dbUser, const String &dbPassword, const String &sqlinterface)
 Open a connection to a database and use that connection. More...
 
bool Connect (const char *host, const char *dbName, const char *dbUser, const char *dbPassword, const char *sqlinterface=NULL)
 Open a connection to a database and use that connection. More...
 
virtual InstanceCount_t decInstance () const
 Decrement the instance. More...
 
bool DeleteResourceId (UpnDbAuthHandle_t AuthHandle, UpnDbResourceId_t ResourceId)
 Delete a Resource ID. More...
 
void Disconnect ()
 Close the connection to the database. More...
 
bool GetAddress (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t UpnId, std::map< const char *, UpnDbAddressRecord *, OrderByIName > &Results) const
 Get the Nth address for a UPN. More...
 
UpnDbRealmId_t GetAddressRealm (UpnDbAddressId_t addrId) const
 Get an address UPNs REALM ID. More...
 
UpnDbUpnId_t GetAddressUpnId (UpnDbAddressId_t addrId) const
 Get an address UPNs ID. More...
 
UpnDbCcId_t GetCc (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, unsigned int Nth) const
 Get the credit card ID for the Nth credit card that belongs to 'upnId'. More...
 
bool GetCcExpire (UpnDbAuthHandle_t AuthHandle, String &Results, UpnDbCcId_t cc) const
 Get expire for the credit card ID for the credit card that belongs to 'upnId'. More...
 
char * GetCcLast4 (UpnDbAuthHandle_t AuthHandle, UpnDbCcId_t cc) const
 Get the last 4 digits of the credit card ID for the credit card that belongs to 'upnId'. More...
 
bool GetEmail (UpnDbAuthHandle_t AuthHandle, String &Results, UpnDbUpnId_t upnId, unsigned int Nth) const
 Get the Nth email address for UPN. More...
 
bool GetEmailAddress (UpnDbAuthHandle_t AuthHandle, std::vector< String *> *Results, UpnDbUpnId_t upnId) const
 Get the Email addresses for a a UPN. More...
 
unsigned int GetErrorCode () const
 Get any error code. More...
 
void GetErrorMessage (String &Results) const
 Get any error message. More...
 
bool GetGUID (String &Results) const
 Get the current application GUID. More...
 
virtual InstanceCount_t getInstance () const
 
bool GetLicense (UpnDbAuthHandle_t AuthHandle, String &Results, UpnDbRealmId_t authRealmId, const String &licenseType, const String &requestCode) const
 Get a license key, given a request code. More...
 
UpnDbLicenseId_t GetLicenseInfo (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t authRealmId, UpnDbUpnId_t upnId, const String &requestCode, const String &licenseKey, const String &product, const String &version, bool &emailSent) const
 Get license information. More...
 
UpnDbRealmId_t GetListRealm (UpnDbMembershipId_t listId) const
 Get a REALM ID from a MEMBER LIST ID. More...
 
UpnDbMembershipId_t GetMembershipId (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realmId, const String &listName) const
 Get the ID given a list name. More...
 
bool GetPref (UpnDbAuthHandle_t AppAuth, UpnDbAuthHandle_t UpnAuth, char *&Results, const char *Key, UpnDbPrefValueTypeId_t &PrefType, unsigned int Index) const
 Get a preference. More...
 
UpnDbPrefId_t GetPrefId (UpnDbAuthHandle_t AppAuth, UpnDbAuthHandle_t UpnAuth, const char *Key, unsigned int Index) const
 Get a preference ID. More...
 
UpnDbRealmId_t GetRealmId (UpnDbAuthHandle_t AuthHandle) const
 Get the REALM id of the AuthHandle_t. More...
 
UpnDbRealmId_t GetRealmId (const String &realm) const
 Get the realm id from a realm name. More...
 
UpnDbRealmId_t GetRealmId (const char *realm) const
 Get the realm id from a realm name. More...
 
const char * GetRealmName (UpnDbRealmId_t Rid) const
 Get the name of the realm, with ID Rid. More...
 
bool GetRealmRecord (UpnDbAuthHandle_t AuthHandle, UpnDbRealmRecord &Results, UpnDbRealmId_t AuthRealmId, const String &Realm) const
 Get the realm record for the named realm. More...
 
bool GetRealmRecord (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t RealmToFind, UpnDbRealmRecord &Results)
 Get a UpnDbRealmRecord from a UpnDbRealmId_t. More...
 
bool GetRealms (UpnDbAuthHandle_t AuthHandle, std::vector< UpnDbRealmRecord *> &Results) const
 Get all realms that can be administered by upnId. More...
 
bool GetRealms (UpnDbAuthHandle_t AuthHandle, std::map< const char *, Realm *> &Results) const
 Get all realms that can be administered by upnId. More...
 
std::list< const char * > * GetRealmsForUpn (UpnDbAuthHandle_t AuthHandle, const char *Upn) const
 Get a list of realms that Upn is in. More...
 
bool GetResource (UpnDbAuthHandle_t AuthHandle, UpnDbResourceId_t Id, String &Name) const
 Get the resource name given a UpnDbResourceId_t. More...
 
bool GetResourceId (UpnDbAuthHandle_t AuthHandle, const char *Name, UpnDbResourceId_t &Results) const
 Get the resource ID type for Name. More...
 
bool GetSpoken (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, String &FileName, String &MimeType, String &Extension) const
 Get the Spoken file for a user. More...
 
SQLGetSQL () const
 Get the associated SQL handle. More...
 
UpnDbUpnId_t GetUpnId (UpnDbAuthHandle_t Handle) const
 The the UPN ID from an authentication handle. More...
 
UpnDbRealmId_t GetUpnRealm (UpnDbUpnId_t upnId) const
 Get a UPNs REALM ID. More...
 
bool GetUserRecord (UpnDbAuthHandle_t Auth, std::map< UpnDbUserId_t, UpnDbUserRecord *> &RecResults, UpnDbUpnId_t TheUpnId) const
 Get a USER RECORD. More...
 
virtual InstanceCount_t incInstance () const
 Increment the instance. More...
 
bool IsAdmin (UpnDbRealmId_t realm, UpnDbUpnId_t upn) const
 Check if UPN has administration rights for realm. More...
 
bool IsAdmin (UpnDbAuthHandle_t AuthHandle) const
 Check if UPN has administration rights for realm. More...
 
bool IsAdminForUpn (UpnDbUpnId_t upn1, UpnDbUpnId_t upn2) const
 Check if upn1 has administration rights for upn2. More...
 
bool IsDecendantRealm (UpnDbAuthHandle_t id, UpnDbRealmId_t ParentRealm, UpnDbRealmId_t ChildRealm)
 Determine if ChildRealm is a child or descendant of ParentRealm. More...
 
bool IsMember (UpnDbAuthHandle_t AuthHandle, UpnDbMembershipId_t listId, UpnDbUpnId_t upnId, String &expireTime)
 Determine if a UPN-ID is a member of LIST-IDa. More...
 
bool IsSiteAdmin (UpnDbUpnId_t upn) const
 Determine if UPN is a site administrator. More...
 
bool IsSiteAdmin (UpnDbAuthHandle_t AuthHandle) const
 Determine if UPN is a site administrator. More...
 
void Logout (UpnDbAuthHandle_t AuthHandle)
 Logout the user. More...
 
void operator delete (void *ToFree)
 
unsigned int PointsTotal (UpnDbUpnId_t upnId)
 Get the UPN's total points. More...
 
bool RemoveAddress (UpnDbAuthHandle_t AuthHandle, UpnDbAddressId_t addrId)
 Delete an address Only the UPN and OR the realm administrator may delete this information. More...
 
bool RemoveCc (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, UpnDbCcId_t cc)
 Delete a Credit card. More...
 
bool RemoveEmail (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, UpnDbEmailId_t emailId)
 Delete an email address. More...
 
bool RemoveMembership (UpnDbAuthHandle_t AuthHandle, UpnDbMembershipId_t listId)
 Remove a membership list. More...
 
bool RemovePref (UpnDbAuthHandle_t AppAuth, UpnDbAuthHandle_t UpnAuth, UpnDbPrefId_t prefId)
 Remove a preference. More...
 
bool RemoveRealm (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realmToRemove, bool force=false)
 Remove a realm. More...
 
bool RemoveRealmAdmin (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realm, UpnDbUpnId_t upnId)
 Remove administrator rights from upnId. More...
 
bool RemoveUpnFromList (UpnDbAuthHandle_t AuthHandle, UpnDbMembershipId_t list, UpnDbUpnId_t upn)
 Remove UPN from realms membership list. More...
 
bool RenameResourceId (UpnDbAuthHandle_t AuthHandle, UpnDbResourceId_t ResourceId, const char *NewName)
 Rename a UpnDbResourceId_t This changes the name of an existing UpnDbResourceId_t For example, you could change the name from "home" to "Home", "any string". More...
 
bool ReparentRealm (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realm, UpnDbRealmId_t newParent)
 Reparent realm. More...
 
UpnDbLicenseId_t SaveLicenseInfo (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t authRealmId, UpnDbUpnId_t upnId, const String &requestCode, const String &licenseKey, const String &product, const String &version, bool emailSent)
 Store or Update license information. More...
 
unsigned int SendEmail (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t authRealmId, UpnDbUpnId_t fromUpnDbUpnId, const String &toListEmail, const String &toListNames, const String &ccListEmail, const String &ccListNames, const String &bccListEmail, const String &bccListNames, const String &errorsToList, const String &subject, const std::vector< String *> &otherHeaders, const String &body, const std::vector< String *> &attachments, const std::vector< String *> &attachMimeType)
 Send email. More...
 
void SetError (SQL *Sql, SQL::SqlQueryId_t qId=0) const
 Get and set the error. More...
 
void SetError (unsigned int code, const char *msg) const
 Record the error. More...
 
void SetLDAP ()
 Future, use LDAP or ActiveDirectory. More...
 
void SetMxHost (const String &mxHost)
 Set the MX host to use when sending email. More...
 
bool SetSpoken (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, String &FileName, String &MimeType, String &Extension)
 Set the Spoken file. More...
 
void SetSQL (SQL *sql, const char *Prefix=NULL)
 Associate a database with this object. More...
 
bool UpdateAddress (UpnDbAuthHandle_t AuthHandle, UpnDbAddressId_t AddrId, UpnDbResourceId_t AddressType, const String &Street1, const String &Street2, const String &City, const String &State, const String &Zip, UpnDbCountryCodeId_t Country)
 Update an existing address information for a UPN Only the UPN OR the realm administrator may add this information. More...
 
bool UpdatePref (UpnDbAuthHandle_t AppAuth, UpnDbAuthHandle_t UpnAuth, UpnDbPrefId_t PrefId, const char *PrefValue)
 Update an existing preference with a new value. More...
 
bool UpdateRealm (UpnDbAuthHandle_t AuthHandle, UpnDbRealmRecord &Rec)
 Update the realm record in the database. More...
 
bool UpdateRealmChild (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t toUpdateId, bool canHaveChild, bool force=false)
 Alter the canHaveChild property of a realm. More...
 
bool UpdateUpn (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, const String &namePrefix, const String &nameFirst, const String &nameMiddle, const String &nameLast, const String &nameSuffix)
 Update UPN name. More...
 
bool UpdateUpn (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, const char *namePrefix, const char *nameFirst, const char *nameMiddle, const char *nameLast, const char *nameSuffix)
 Update UPN name. More...
 
bool UpdateUpnInList (UpnDbAuthHandle_t AuthHandle, UpnDbMembershipId_t list, UpnDbUpnId_t upn, const String &expire)
 Update the expire time for UPN from realms membership list. More...
 
unsigned int UrlViewed (UpnDbUpnId_t upnId, const String &urlVisited)
 Track that upId viewed urlVisited. More...
 
bool ValidAuthHandle (UpnDbAuthHandle_t AuthHandle) const
 Validate the AuthHandle_t, the user must be authenticated. More...
 
bool VerifyPassword (UpnDbAuthHandle_t AuthHandle, const char *Password)
 Check to see if the caller knows the password for Auth. More...
 
bool VerifyPassword (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t ForUpnId, const char *Password)
 Check to see if the caller knows the password for Auth. More...
 

Static Public Member Functions

static bool CreateSqlDatabase (const char *DatabaseHost, const char *DatabaseName, const char *DatabaseUserName, const char *DatabaseUserPassword, unsigned short DatabasePort, const char *DatabaseUpnDbPrefix, const char *RuntimeUsername, const char *RuntimePassword, const char *DatabaseType, const char *InitFiles, String &ErrorMessages)
 Initialize a database to use this object. More...
 
static UpnDbRealmId_t GetRealmId (const String &realm, SQL *sql, const char *Prefix)
 Get the realm id from a realm name. More...
 
static UpnDbRealmId_t GetRealmId (const char *realm, SQL *sql, const char *Prefix)
 Get the realm id from a realm name. More...
 
static UpnDBGetUpnDb (UpnDbAuthHandle_t AuthHandle)
 Validate the AuthHandle_t, the user must be authenticated. More...
 

Protected Member Functions

UpnDbRealmId_t _GetCcRealm (UpnDbCcId_t id) const
 Get the REALM ID for a specific credit card. More...
 
UpnDbUpnId_t _GetCcUpn (UpnDbCcId_t id) const
 Get the UPN ID for a specific credit card. More...
 

Protected Attributes

unsigned int _ErrorCode
 The last error code. More...
 
const char * _ErrorMessage
 The last error message. More...
 
bool _OurSql
 If we allocated the _sql variable this will be TRUE. More...
 
const char * _Prefix
 The database object prefix to use for all SQL objects. More...
 
UpnDbRealmId_t _Realm
 REALM ID of the last authenticated UPN. More...
 
SQL_Sql
 The SQL handle to the database being used. More...
 
UpnDbUpnId_t _Upn
 ID of the last authenticated UPN. More...
 

Static Protected Attributes

static const char * _GUID
 The GUID for the currently authenticated application. More...
 

Detailed Description

UPN (user) database objects.

Definition at line 168 of file UpnDB.hpp.

Constructor & Destructor Documentation

◆ UpnDB()

SoftwareAndServices::Library::UPN::UpnDB::UpnDB ( )

UpnDB - default Constructor.

◆ ~UpnDB()

virtual SoftwareAndServices::Library::UPN::UpnDB::~UpnDB ( )
virtual

UpnDB - destructor.

Member Function Documentation

◆ _GetCcRealm()

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::_GetCcRealm ( UpnDbCcId_t  id) const
protected

Get the REALM ID for a specific credit card.

Parameters
idThe Credit card ID
Returns
The UpnDbRealmId_t of that credit card.

◆ _GetCcUpn()

UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDB::_GetCcUpn ( UpnDbCcId_t  id) const
protected

Get the UPN ID for a specific credit card.

Parameters
idThe Credit card ID
Returns
The UpnDbUpnId_t of that credit card.

◆ AddAddress() [1/2]

UpnDbAddressId_t SoftwareAndServices::Library::UPN::UpnDB::AddAddress ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
UpnDbResourceId_t  addressType,
const String street1,
const String street2,
const String city,
const String state,
const String zip,
const String country 
)

Add address information for a UPN.

Only the UPN OR the realm administrator may add this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID to apply the address info.
addressTypeThe name of this address (WORK, HOME, ...)
street1Line one of the street address.
street2Line two of the street address.
cityThe city (locality).
stateThe state (province).
zipThe Zip Code (postal code).
countryThe Country.
Returns
The new UpnDbAddressId or zero on error.

◆ AddAddress() [2/2]

UpnDbAddressId_t SoftwareAndServices::Library::UPN::UpnDB::AddAddress ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  UpnId,
UpnDbResourceId_t  AddressType,
const String Street1,
const String Street2,
const String City,
const String State,
const String Zip,
UpnDbCountryCodeId_t  Country 
)

Add address information for a UPN.

Only the UPN OR the realm administrator may add this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
UpnIdThe UPN ID to apply the address info.
AddressTypeThe name of this address (WORK, HOME, ...)
Street1Line one of the street address.
Street2Line two of the street address.
CityThe city (locality).
StateThe state (province).
ZipThe Zip Code (postal code).
CountryThe Country.
Returns
The new UpnDbAddressId or zero on error.

◆ AddCc()

UpnDbCcId_t SoftwareAndServices::Library::UPN::UpnDB::AddCc ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
UpnDbAddressId_t  addrId,
const String number,
unsigned char  expireMonth,
unsigned short  expireYear,
const String back,
const char  type,
const String cardHoldersName 
)

Add credit card information for upnId.

The credit card information is encrypted in the database. Only an administrator or the UPN UPN can add CC info.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID to apply the CC info.
addrIdThe address to associate with this card.
numberThe credit card info.
expireMonthThe expiration month of the card.
expireYearThe expiration year of the card (4 digits).
backThe check digits on the back of the card.
typeA single character: 'V' (Visa), 'A' (AmEx), 'M' (MasterCard) 'D' (Discovery).
cardHoldersNameThe card holders name as it appears on the card.
Returns
The Credit card ID or zero on error.

◆ AddEmail()

UpnDbEmailId_t SoftwareAndServices::Library::UPN::UpnDB::AddEmail ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
UpnDbResourceId_t  ResourceType,
const String Email,
const String Name 
)

Add email information for a UPN.

Only the UPN OR the realm administrator may add this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID to apply the email info.
ResourceTypeThe name of this address (WORK, HOME, ...)
EmailThe email address to add.
NameThe name (optional) to associate with the email. For a person, this often is the persons name.
Returns
The new UpnDbAddressId or zero on error.

◆ AddMembership()

UpnDbMembershipId_t SoftwareAndServices::Library::UPN::UpnDB::AddMembership ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realm,
const String name 
)

Create a new membership list.

Parameters
realmThe realm for the new membership list.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
nameThe name of the new membership list.
Returns
The new membership list id, or zero on error.

◆ AddPref()

UpnDbPrefId_t SoftwareAndServices::Library::UPN::UpnDB::AddPref ( UpnDbAuthHandle_t  AppAuth,
UpnDbAuthHandle_t  UpnAuth,
const char *  PrefKey,
UpnDbPrefValueTypeId_t  PrefType,
const char *  PrefValue,
unsigned int  Index = 0 
)

Add a new user preference.

Parameters
AppAuthThe UPN authentication handle for the application.
UpnAuthThe UPN authentication handle for the user (UPN's authentication handle).
PrefKeyA string to be used as the name of the preference. The string must be more than 5 characters/numbers in length. A key strings must consist of values from the printable ASCII characters set (A-Z, a-Z, 0-9, underscore, dash, and colon, or slash):
A-Z a-z 0-9 _ - : /
PrefValueA string that is the preference value. To add an empty value, set prefValue to the empty string ("");
PrefTypeThe type of the preference.

A NULL value can NOT be added. A prefValue can be any string accepted by SQL as a variable length char array or string.

Parameters
IndexSet INDEX to index for this value. Allows for multiple values per key. Index starts with zero.
Returns
TRUE if added. FALSE on failure. Will also fail if 'prefKey' already exists in realm, for UPN, and 'appName'.

◆ AddRealm() [1/2]

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::AddRealm ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  ParentRealm,
const String NewRealm,
const String Description,
bool  CanHaveChild = true,
bool  CanHaveUpns = true,
bool  CanRemove = true,
bool  Disabled = false 
)

Add realm.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ParentRealmThe parent realm id (zero == root)
NewRealmThe name of the new realm.
DescriptionThe description of the realm. Describes the realm name, usage, or other information to a user. May be empty. Recommend filling this in.
CanHaveChildIf TRUE, this realm can be the parent of other realms.
CanHaveUpnsWhen TRUE, this realm may have UPNs associated with it.
CanRemoveWhen false, this realm may NOT be removed. Only a site administrator can create a non-removable realm.
Note
CAUTION, this really means it can not be removed!
Parameters
disabledWhen true, the realm is created disabled.
Returns
The new realm ID.

◆ AddRealm() [2/2]

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::AddRealm ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  ParentRealm,
const char *  NewRealm,
const char *  Description,
bool  CanHaveChild = true,
bool  CanHaveUpns = true,
bool  CanRemove = true,
bool  Disabled = false 
)

Add realm.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ParentRealmThe parent realm id (zero == root)
NewRealmThe name of the new realm.
DescriptionThe description of the realm. Describes the realm name, usage, or other information to a user. May be empty. Recommend filling this in.
CanHaveChildIf TRUE, this realm can be the parent of other realms.
CanHaveUpnsWhen TRUE, this realm may have UPNs associated with it.
CanRemoveWhen false, this realm may NOT be removed. Only a site administrator can create a non-removable realm.
Note
CAUTION, this really means it can not be removed!
Parameters
disabledWhen true, the realm is created disabled.
Returns
The new realm ID.

◆ AddRealmAdmin()

bool SoftwareAndServices::Library::UPN::UpnDB::AddRealmAdmin ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realm,
UpnDbUpnId_t  upnId 
)

Make an existing UPN a realm administrator.

If the realm is the id of the 'root' node, then upnId is a site administrator..

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
realmThe REALM ID that upnId is to be an administrator.
upnIdThe ID to make a realm or site administrator.
Returns
TRUE if upnId was added as a realm or site administrator.

◆ AddResourceId()

UpnDbResourceId_t SoftwareAndServices::Library::UPN::UpnDB::AddResourceId ( UpnDbAuthHandle_t  AuthHandle,
UpnDbResourceId_t  System,
const char *  Name 
)

Add a new resource name.

if it already exists, nothing is done.

There are two types: User named types (UpnDbResourceId_t) and system types (UpnDbResourceTypeId_t).

The user type (UpnDbResourceId_t allows for UPNs to use a localized name for a system resource (UpnDbResourceTypeId_t).

Parameters
AuthHandleThe authentication handle of the the requestor.
SystemThe system UpnResourceTypeId_t.
NameThe name to add. Name is case insensitive. If one already exists called 'home', you can not add one called 'HOME', 'Home', or any other mixed case variation.
[out]SystemThe UpnDbResourceTypeId_t type.
Returns
The new UpnDbResourceId_t, or zero if it already exists. It can also return zero if AuthHandle does not have the authority to add the information.

◆ AddUpnToList()

bool SoftwareAndServices::Library::UPN::UpnDB::AddUpnToList ( UpnDbAuthHandle_t  AuthHandle,
UpnDbMembershipId_t  list,
UpnDbUpnId_t  upn,
const String expire 
)

Add UPN to realms membership list.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
listThe list to be added to.
upnThe UPN to add.
expireIf not NULL, the expire time (DDMMYYYY) or (DDMMYYYYTHHMMSS). When the UPN expires, they will remain inactive on the list until the expire date is reset or they are removed from the list.
Returns
TRUE if added.

◆ AppLogin() [1/2]

UpnDbAuthHandle_t SoftwareAndServices::Library::UPN::UpnDB::AppLogin ( const String GUID,
const String password,
const String appGUID,
const String appPassword,
const String host,
const String db 
)

This is used by an application to find if it has access to UpnDB.

This is for 'application's, not persons. (Does app-'GUID' have access to 'appGUID' and has it supplied the correct password). This is part of a runtime license.

Not all applications have runtime licenses.

Parameters
AdminUpnThe UPN to login to the UPN database with.
passwordThe AdminUpn password.
appGUIDThe application GUID to check.
appPasswordThe appGUID password.
hostThe database host to use.
dbThe database to connect to.
Returns
An authentication handle.

◆ AppLogin() [2/2]

UpnDbAuthHandle_t SoftwareAndServices::Library::UPN::UpnDB::AppLogin ( const char *  GUID,
const char *  password,
const char *  appGUID,
const char *  appPassword,
const char *  host,
const char *  db 
)

This is used by an application to find if it has access to UpnDB.

This is for 'application's, not persons. (Does app-'GUID' have access to 'appGUID' and has it supplied the correct password). This is part of a runtime license.

Not all applications have runtime licenses.

Parameters
GUIDThe UPN to login with.
passwordThe GUID password.
appGUIDThe application GUID to check.
appPasswordThe appGUID password.
hostThe database host to use.
dbThe database to connect to.
Returns
An authentication handle.

◆ Authenticate() [1/3]

UpnDbAuthHandle_t SoftwareAndServices::Library::UPN::UpnDB::Authenticate ( X509_STORE_CTX *  Store,
const char *const  Upn,
const char *const  Realm,
const char *const  RemoteHost = nullptr,
int16_t  RemotePort = 0 
)

Authenticate a secure connection.

A certificate and chain is requesting authentication and authorization to a Upn/Realm.

This library contacts the authentication server to validate that Store is a valid certificate and chain.

Then this library contacts the authorization server to validate that Store has permission to access the Upn/Realm server or application.

This is also used by the runtime license verification processes. The Store would be the instance certificate and chain for the application, and the Upn/Realm are for the application itself. When a non-zero is returned, the license is valid.

Parameters
StoreThe certificate and chain to verify.
UpnStore is requesting access to application or server 'Upn' UPN.
AcessToUpnStore is requesting access to application or server 'Realm' realm.
RemoteHostOptional The host name to connect to. When RemoteHost is nullptr, then only local data will be checked.
RemotePortThe port number to use for the authentication. When RemoteHost is non-nullptr, then RemotePort must be a valid TCP port number on RemoteHost. When RemotePort is zero (0), then remote host will be ignored and no remote connection will be attempted.
Returns
The authentication handle to use in following UpnDB library methods. On error or when Store is not authorized or authenticated, then will return zero (0).

For runtime license checking, a handle is returned. When zero (0) is returned, the run-time license is not valid, or no longer valid. The calling application would return an error, or backup to a demo/setup certificate and try again.

A non-zero value will be returned when Store is accepted as a valid authentication and it is authorized to communicate with Upn/Realm.

◆ Authenticate() [2/3]

UpnDbAuthHandle_t SoftwareAndServices::Library::UPN::UpnDB::Authenticate ( UpnDbRealmId_t  realm,
const String upn,
const String pw 
)

Authenticate UPN.

Returns the ID of the UPN on success.

Parameters
realmThe realm id to authenticate against.
upnThe UPN to authenticate.
pwThe password to test.
Returns
The UPN ID if correct, else zero. If authentication FAILS, then this API sleeps for several seconds before returning in order to stop automated hacking attempts.

◆ Authenticate() [3/3]

UpnDbAuthHandle_t SoftwareAndServices::Library::UPN::UpnDB::Authenticate ( UpnDbRealmId_t  realm,
const char *  upn,
const char *  pw 
)

Authenticate UPN.

Returns the ID of the UPN on success.

Parameters
realmThe realm id to authenticate against.
upnThe UPN to authenticate.
pwThe password to test.
Returns
The UPN ID if correct, else zero. If authentication FAILS, then this API sleeps for several seconds before returning in order to stop automated hacking attempts.

◆ CanHaveChildren()

bool SoftwareAndServices::Library::UPN::UpnDB::CanHaveChildren ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  RealmId 
)

Find out if the named realm can have child realms.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
RealmIdThe realm ID to check.
Returns
TRUE when it can have child realms.

◆ ChargeCc()

bool SoftwareAndServices::Library::UPN::UpnDB::ChargeCc ( UpnDbAuthHandle_t  AuthHandle,
UpnDbCcId_t  cc,
const String partNumber,
const String description,
const String amount 
)

Charge a credit card.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ccThe credit card ID.
partNumberThe part number being bought.
descriptionThe description of the item being bought.
amountThe amount to charge the card.
Returns
The last expire data as MMYYYY (022004) in a string.

◆ ChargeCcMonthly()

bool SoftwareAndServices::Library::UPN::UpnDB::ChargeCcMonthly ( UpnDbAuthHandle_t  AuthHandle,
UpnDbCcId_t  cc,
const String partNumber,
const String description,
const String amount 
)

Charge a credit card monthly.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ccThe credit card ID.
partNumberThe part number being bought.
descriptionThe description of the item being bought.
amountThe amount to charge the card each month.
Returns
TRUE if card was charged.

◆ ChargeCcYearly()

bool SoftwareAndServices::Library::UPN::UpnDB::ChargeCcYearly ( UpnDbAuthHandle_t  AuthHandle,
UpnDbCcId_t  cc,
const String partNumber,
const String description,
const String amount 
)

Charge a credit card yearly.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ccThe credit card ID.
partNumberThe part number being bought.
descriptionThe description of the item being bought.
amountThe amount to charge the card each year.
Returns
TRUE if card was charged.

◆ Connect() [1/2]

bool SoftwareAndServices::Library::UPN::UpnDB::Connect ( const String host,
const String dbName,
const String dbUser,
const String dbPassword,
const String sqlinterface 
)

Open a connection to a database and use that connection.

Parameters
hostThe host name of the database server.
dbNameThe name of the database to use.
dbUserThe name of the database user.
dbPasswordThe password for the database user.
sqlinterfaceThe name of the interface 'mysql', 'postgres', or other databases supported by the SQL interface.
Returns
TRUE if connection is successful.

◆ Connect() [2/2]

bool SoftwareAndServices::Library::UPN::UpnDB::Connect ( const char *  host,
const char *  dbName,
const char *  dbUser,
const char *  dbPassword,
const char *  sqlinterface = NULL 
)

Open a connection to a database and use that connection.

Parameters
hostThe host name of the database server.
dbNameThe name of the database to use.
dbUserThe name of the database user.
dbPasswordThe password for the database user.
sqlinterfaceThe name of the interface 'mysql', 'postgres', or other databases supported by the SQL interface.
Returns
TRUE if connection is successful.

◆ CreateSqlDatabase()

static bool SoftwareAndServices::Library::UPN::UpnDB::CreateSqlDatabase ( const char *  DatabaseHost,
const char *  DatabaseName,
const char *  DatabaseUserName,
const char *  DatabaseUserPassword,
unsigned short  DatabasePort,
const char *  DatabaseUpnDbPrefix,
const char *  RuntimeUsername,
const char *  RuntimePassword,
const char *  DatabaseType,
const char *  InitFiles,
String ErrorMessages 
)
static

Initialize a database to use this object.

This is done once per database. This creates the tables, procedures, views, triggers, foreign keys, and other database object needed by UpnDB.

Parameters
DatabaseHostThe hostname or IP address of where the database is stored.
DatabaseNameThe name of the database to connect with.
DatabaseUserNameA database user name with sufficient privileges to allow all objects to be created.
DatabaseUserPasswordThe password associated with DatabaseUserName.
DatabasePortThe port number to use, if -1 it will be the default for the database provider.
DatabaseUpnDbPrefixA prefix to use with all objects to be created. If NULL, then a Software And Services UpnDB one 'sas_' will be prepended to the name of all database objects created.
RuntimeUsernameThe username that the UpnDB object will use at runtime to access the database. RuntimeUsername needs to have been already created with permissions to access the database from the locations you need. This will be tested prior to this method returning.
RuntimePasswordThe password associated with UpnDbUsername.

The RuntimeUsername must have already been setup with with RuntimePassword.

Parameters
DatabaseTypeCurrently only "mysql" and "postgres" are supported.
InitFilesThe file prefix name that will contain the sqlcommands. It will open two files.
  • SQL File:
    This library will append '.sql' to the InitFiles name and use the contents of the generated file name to create the database.
  • Initialization File:
    This library will append '.seed' to the InitFiles name and use the contents of the generated file name to seed the the contents of the new database.

  • When InitFiles is NULL, then it will look into the installation directory for files. The installation directory is determined by first looking for an environmental variable "SAS_LIBSASUSER_DIR", if not set, then it looks for "SAS_LIB_DIR". If that is not set, then it will look for "SAS_DIR. If none are present, then it will assume the default installation directory of root for UNIX/Linux type systems. For Microsoft windows, it will look in the directory in which this library was installed.
    - For <b>PostgreSql</b> the default files will be:
        - {installation-directory}/etc/SaS/User/Initialization.pg.sql
        - {installation-directory}/etc/SaS/User/Initialization.pg.seed
    


    • For MySql the default files will be:
      • {installation-directory}/etc/SaS/User/Initialization.my.sql
      • {installation-directory}/etc/SaS/User/Initialization.my.seed

ErrorMessagesA reference to an existing String object. When this method returns FALSE, any error messages will be appended to ErrorMessages.
Returns
TRUE if successful.

◆ decInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< UpnDB >::decInstance ( ) const
inlinevirtualinherited

Decrement the instance.

Returns
The instance count, after decrementing it.

Definition at line 129 of file instance.hpp.

◆ DeleteResourceId()

bool SoftwareAndServices::Library::UPN::UpnDB::DeleteResourceId ( UpnDbAuthHandle_t  AuthHandle,
UpnDbResourceId_t  ResourceId 
)

Delete a Resource ID.

Parameters
AuthHandleThe authentication handle of the the requestor.
ResourceIdThe ID to delete.
Returns
true, if deleted. If it does not exist, or if AuthHandle does not the authority do delete a resource.

◆ Disconnect()

void SoftwareAndServices::Library::UPN::UpnDB::Disconnect ( )

Close the connection to the database.

Returns
TRUE if connection is successful.

◆ GetAddress()

bool SoftwareAndServices::Library::UPN::UpnDB::GetAddress ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  UpnId,
std::map< const char *, UpnDbAddressRecord *, OrderByIName > &  Results 
) const

Get the Nth address for a UPN.

Only the UPN and OR the realm administrator may get an address for a user.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
UpnIdThe UpnId to fetch.
[out]ResultsA std::map<const char * Name, UpnDbAddressRecord*> of the results. The results will be sorted by name using strncasecmp() (stricmp() on some systems).

When done, call delete for each Name to free up, and FreeUpnDbAddressRecord() for each UpnDbAddressRecord to delete.

Note
: This method appends to the results Results variable, so provide an empty map when you only want this calls results.
Returns
A true if any found and appended to Results. Caller must free the Name and UpnDbAddress Record results when finished using the data.

◆ GetAddressRealm()

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::GetAddressRealm ( UpnDbAddressId_t  addrId) const

Get an address UPNs REALM ID.

Parameters
addrIdThe ID of an address on the system.
Returns
The REALM ID or zero if upnId is invalid.

◆ GetAddressUpnId()

UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDB::GetAddressUpnId ( UpnDbAddressId_t  addrId) const

Get an address UPNs ID.

Parameters
addrIdThe UPN of a user on the system.
Returns
The UPN ID or zero if upnId is invalid.

◆ GetCc()

UpnDbCcId_t SoftwareAndServices::Library::UPN::UpnDB::GetCc ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
unsigned int  Nth 
) const

Get the credit card ID for the Nth credit card that belongs to 'upnId'.

Only the UPN and OR the realm administrator may get this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID for the card to get.
NthThe nth card ID to get (starts from zero)
Returns
The Credit Card ID.

◆ GetCcExpire()

bool SoftwareAndServices::Library::UPN::UpnDB::GetCcExpire ( UpnDbAuthHandle_t  AuthHandle,
String Results,
UpnDbCcId_t  cc 
) const

Get expire for the credit card ID for the credit card that belongs to 'upnId'.

Only the UPN and OR the realm administrator may get this information.

Parameters
ResultsA pointer to a String where the results are appended.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ccThe credit card ID.
Returns
The last expire data as MMYYYY (022004) in a string. Caller MUST free results.

◆ GetCcLast4()

char* SoftwareAndServices::Library::UPN::UpnDB::GetCcLast4 ( UpnDbAuthHandle_t  AuthHandle,
UpnDbCcId_t  cc 
) const

Get the last 4 digits of the credit card ID for the credit card that belongs to 'upnId'.

Only the UPN and OR the realm administrator may get this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ccThe credit card ID.
Returns
The last 4 digits of the credit card. Caller MUST free results.

◆ GetEmail()

bool SoftwareAndServices::Library::UPN::UpnDB::GetEmail ( UpnDbAuthHandle_t  AuthHandle,
String Results,
UpnDbUpnId_t  upnId,
unsigned int  Nth 
) const

Get the Nth email address for UPN.

Only the UPN and OR the realm administrator may delete this information.

Parameters
ResultsWhere the results will be appended to.
upnIdThe UPN ID to fetch..
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
NthThe nTh email address to fetch (starts at zero).
Returns
TRUE when Results have content.

◆ GetEmailAddress()

bool SoftwareAndServices::Library::UPN::UpnDB::GetEmailAddress ( UpnDbAuthHandle_t  AuthHandle,
std::vector< String *> *  Results,
UpnDbUpnId_t  upnId 
) const

Get the Email addresses for a a UPN.

Parameters
ResultsA std::vector<String*> of results. Caller must delete each (String*) when done.
upnIdThe UPN-ID to search.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
Returns
TRUE when there are any matches.

◆ GetErrorCode()

unsigned int SoftwareAndServices::Library::UPN::UpnDB::GetErrorCode ( ) const

Get any error code.

Returns
Any error code that may have been saved. May return 0 if there is no error code that can be generated.

◆ GetErrorMessage()

void SoftwareAndServices::Library::UPN::UpnDB::GetErrorMessage ( String Results) const

Get any error message.

Parameters
ResultsA pointer to a String where the results will be appended.

◆ GetGUID()

bool SoftwareAndServices::Library::UPN::UpnDB::GetGUID ( String Results) const

Get the current application GUID.

Parameters
ResultsA pointer to a String where the results will be appended.
Returns
TRUE if found and appended to Results.

◆ getInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< UpnDB >::getInstance ( ) const
inlinevirtualinherited
Returns
The current instance count.

Definition at line 118 of file instance.hpp.

◆ GetLicense()

bool SoftwareAndServices::Library::UPN::UpnDB::GetLicense ( UpnDbAuthHandle_t  AuthHandle,
String Results,
UpnDbRealmId_t  authRealmId,
const String licenseType,
const String requestCode 
) const

Get a license key, given a request code.

Parameters
ResultsA pointer to where the results will be appended.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
authRealmIdThe realm ID to authenticate against.
licenseTypeA string that tells the license server what type of license to get. For SoftwareShield, its the .lpj file name.
requestCodeThe request code that specifies the license type get generate.
Returns
TRUE if Results have the appended to it.

◆ GetLicenseInfo()

UpnDbLicenseId_t SoftwareAndServices::Library::UPN::UpnDB::GetLicenseInfo ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  authRealmId,
UpnDbUpnId_t  upnId,
const String requestCode,
const String licenseKey,
const String product,
const String version,
bool &  emailSent 
) const

Get license information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
authRealmIdThe realm ID to authenticate against.
upnIdThe UPN associated with the license.
requestCodeThe request code to authenticate.
[out]licenseKeyThe valid license key.
[out]productThe product name being licensed.
[out]versionThe product version being licensed.
[out]emailSentSet to true if the UPN was sent email.
Returns
The ID for this license.

◆ GetListRealm()

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::GetListRealm ( UpnDbMembershipId_t  listId) const

Get a REALM ID from a MEMBER LIST ID.

Parameters
listIdThe ID a membership list.
Returns
The UPN ID or zero if memberId is invalid.

◆ GetMembershipId()

UpnDbMembershipId_t SoftwareAndServices::Library::UPN::UpnDB::GetMembershipId ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realmId,
const String listName 
) const

Get the ID given a list name.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
realmIdThe ID of the realm that contains listName.
listNameThe name of the list.
Returns
The list ID or zero if it does not exist.

◆ GetPref()

bool SoftwareAndServices::Library::UPN::UpnDB::GetPref ( UpnDbAuthHandle_t  AppAuth,
UpnDbAuthHandle_t  UpnAuth,
char *&  Results,
const char *  Key,
UpnDbPrefValueTypeId_t &  PrefType,
unsigned int  Index 
) const

Get a preference.

Parameters
AppAuthThe UPN authentication handle for the application.
UpnAuthThe UPN authentication handle for the user (UPN's authentication handle).
ResultsWhere the result will be stored.
KeyA key for the preference.
PrefTypeThe value type for Results. Its always a string, PrefType specifies the content type of the staring (boolean true,fale, float ...)
IndexGet value with INDEX set to index Index starts with zero.
Returns
true if found.

◆ GetPrefId()

UpnDbPrefId_t SoftwareAndServices::Library::UPN::UpnDB::GetPrefId ( UpnDbAuthHandle_t  AppAuth,
UpnDbAuthHandle_t  UpnAuth,
const char *  Key,
unsigned int  Index 
) const

Get a preference ID.

Parameters
AppAuthThe UPN authentication handle for the application.
UpnAuthThe UPN authentication handle for the user (UPN's authentication handle).
KeyA key for the preference.
IndexWhich value, first is zero.
Returns
The preference ID, or zero if it does not exist.

◆ GetRealmId() [1/5]

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::GetRealmId ( UpnDbAuthHandle_t  AuthHandle) const

Get the REALM id of the AuthHandle_t.

Parameters
AuthHandleThe handle from a successful authentication.
Returns
the UpnDbRealmId_t or zero if not available or authenticated.

◆ GetRealmId() [2/5]

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::GetRealmId ( const String realm) const

Get the realm id from a realm name.

Parameters
realmThe realm to be searched.
Returns
The id of 'realm'.

◆ GetRealmId() [3/5]

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::GetRealmId ( const char *  realm) const

Get the realm id from a realm name.

Parameters
realmThe realm to be searched.
Returns
The id of 'realm'.

◆ GetRealmId() [4/5]

static UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::GetRealmId ( const String realm,
SQL sql,
const char *  Prefix 
)
static

Get the realm id from a realm name.

Parameters
realmThe realm to be searched.
sqlA connected SQL object.
PrefixThe database object prefix used.
Returns
The id of 'realm'.

◆ GetRealmId() [5/5]

static UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::GetRealmId ( const char *  realm,
SQL sql,
const char *  Prefix 
)
static

Get the realm id from a realm name.

Parameters
realmThe realm to be searched.
sqlA connected SQL object.
PrefixThe database object prefix used.
Returns
The id of 'realm'.

◆ GetRealmName()

const char* SoftwareAndServices::Library::UPN::UpnDB::GetRealmName ( UpnDbRealmId_t  Rid) const

Get the name of the realm, with ID Rid.

Parameters
RidThe ID of the realm to get the name of.
Returns
The realm name, or NULL when not found, or permission denied.

◆ GetRealmRecord() [1/2]

bool SoftwareAndServices::Library::UPN::UpnDB::GetRealmRecord ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmRecord Results,
UpnDbRealmId_t  AuthRealmId,
const String Realm 
) const

Get the realm record for the named realm.

Parameters
ResultsA pointer to UpnDbRealmRecord where the results will be stored.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
AuthRealmIdThe realm ID to authenticate against.
RealmThe realm name to fetch.
Returns
A pointer to a record, or NULL on error.

◆ GetRealmRecord() [2/2]

bool SoftwareAndServices::Library::UPN::UpnDB::GetRealmRecord ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  RealmToFind,
UpnDbRealmRecord Results 
)

Get a UpnDbRealmRecord from a UpnDbRealmId_t.

Parameters
AuthHandleA site or realm administrator authentication handle, or the authentication handle of a user that is in RealmToFind.
RealmToFindThe UpnDbRealmId_t to locate.
ResultsA reference to a UpnDbRealmRecord object where the results will be put.
Returns
true on success. On success Results will be filled in. On failure, Results will not be touched.

◆ GetRealms() [1/2]

bool SoftwareAndServices::Library::UPN::UpnDB::GetRealms ( UpnDbAuthHandle_t  AuthHandle,
std::vector< UpnDbRealmRecord *> &  Results 
) const

Get all realms that can be administered by upnId.

If AuthHandle is not a realm or site administrator, then false is returned.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ResultsA reference to a vector of UpnDbRealmRecord where the results will be stored.
Returns
TRUE if any are found.

◆ GetRealms() [2/2]

bool SoftwareAndServices::Library::UPN::UpnDB::GetRealms ( UpnDbAuthHandle_t  AuthHandle,
std::map< const char *, Realm *> &  Results 
) const

Get all realms that can be administered by upnId.

If AuthHandle is not a realm or site administrator, then FALSE is returned.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ResultsA reference to a std::map<const char *, Realm*> where the results will be stored.
Returns
TRUE if any are found.

◆ GetRealmsForUpn()

std::list<const char*>* SoftwareAndServices::Library::UPN::UpnDB::GetRealmsForUpn ( UpnDbAuthHandle_t  AuthHandle,
const char *  Upn 
) const

Get a list of realms that Upn is in.

If AuthHandle is not a realm or site administrator, then NULL is returned.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
UpnThe UPN to search for.
Returns
A std::list<const char*> of realms names. Or NULL when none.

◆ GetResource()

bool SoftwareAndServices::Library::UPN::UpnDB::GetResource ( UpnDbAuthHandle_t  AuthHandle,
UpnDbResourceId_t  Id,
String Name 
) const

Get the resource name given a UpnDbResourceId_t.

Parameters
AuthHandleThe authentication handle of the the requestor.
IdThe UpnDbResourceId_t to get the name of.
[out]SystemThe system UpnResourceTypeId_t type.
[out]NameThe name found. Name will be set to the name of the UpnDbResourceId_t if it exists and if AuthHandle is authroized to fetch the value.
Returns
true if found and Name was updated. False if not found, or AuthHandle is not authorized to fetch the data.

◆ GetResourceId()

bool SoftwareAndServices::Library::UPN::UpnDB::GetResourceId ( UpnDbAuthHandle_t  AuthHandle,
const char *  Name,
UpnDbResourceId_t &  Results 
) const

Get the resource ID type for Name.

Parameters
AuthHandleThe authentication handle of the the requestor.
NameThe name to look for. It is a case insensitive search.
[out]ResultsThe UpnDbResourceId_t if found, else zero. It can also return zero if AuthHandle does not have the authority to fetch the information.
[out]SystemResultsThe UpnDbResourceTypeId_t.
Returns
true if found and Results and SystemResults are filled in.

◆ GetSpoken()

bool SoftwareAndServices::Library::UPN::UpnDB::GetSpoken ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
String FileName,
String MimeType,
String Extension 
) const

Get the Spoken file for a user.

How to pronounce their name.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN associated with the file.
FileNameThe file name where the the spoken file will be placed.
[out]MimeTypeThe MIME type of the spoken file.
[out]ExtensionFile extension. If known, set, else empty.
Returns
true if the data was located and MimeType and Extension (if it was originally set) are filled in.

◆ GetSQL()

SQL* SoftwareAndServices::Library::UPN::UpnDB::GetSQL ( ) const
inline

Get the associated SQL handle.

Returns
The SQL handle.

Definition at line 1991 of file UpnDB.hpp.

◆ GetUpnDb()

static UpnDB* SoftwareAndServices::Library::UPN::UpnDB::GetUpnDb ( UpnDbAuthHandle_t  AuthHandle)
static

Validate the AuthHandle_t, the user must be authenticated.

Parameters
AuthHandleAn active authentication handle.
Returns
TRUE if authenticated and valid.

◆ GetUpnId()

UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDB::GetUpnId ( UpnDbAuthHandle_t  Handle) const

The the UPN ID from an authentication handle.

Parameters
HandleThe authentication handle.
Returns
The UPN ID that was used to authenticate.

◆ GetUpnRealm()

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::GetUpnRealm ( UpnDbUpnId_t  upnId) const

Get a UPNs REALM ID.

Parameters
upnIdThe UPN of a user on the system.
Returns
The REALM ID or zero if upnId is invalid.

◆ GetUserRecord()

bool SoftwareAndServices::Library::UPN::UpnDB::GetUserRecord ( UpnDbAuthHandle_t  Auth,
std::map< UpnDbUserId_t, UpnDbUserRecord *> &  RecResults,
UpnDbUpnId_t  TheUpnId 
) const

Get a USER RECORD.

Parameters
AuthThe handle to the currently authenticated UPN.
ResultsA reference to a std::map<UpnDbUserId_t, UpnDbUserRecord*> that will be filled in if return value is TRUE.
TheUpnIdThe UPN-ID of a user on the system.
Returns
TRUE when any are found and Results are filled in.

◆ incInstance()

virtual InstanceCount_t SoftwareAndServices::Library::Common::instance< UpnDB >::incInstance ( ) const
inlinevirtualinherited

Increment the instance.

Returns
The instance value, after incrementing it.

Definition at line 109 of file instance.hpp.

◆ IsAdmin() [1/2]

bool SoftwareAndServices::Library::UPN::UpnDB::IsAdmin ( UpnDbRealmId_t  realm,
UpnDbUpnId_t  upn 
) const

Check if UPN has administration rights for realm.

Parameters
realmThe realm of interest or any if NULL.
upnThe id of UPN being tested for administrator rights.
Returns
TRUE if UPN is an administrator for realm.

◆ IsAdmin() [2/2]

bool SoftwareAndServices::Library::UPN::UpnDB::IsAdmin ( UpnDbAuthHandle_t  AuthHandle) const

Check if UPN has administration rights for realm.

Parameters
AuthHandleThe handle of an authenticated UPN being tested for administrator rights.
Returns
TRUE if UPN is an administrator for realm.

◆ IsAdminForUpn()

bool SoftwareAndServices::Library::UPN::UpnDB::IsAdminForUpn ( UpnDbUpnId_t  upn1,
UpnDbUpnId_t  upn2 
) const

Check if upn1 has administration rights for upn2.

Parameters
upn1The id of UPN being tested for administrator rights over upn2.
upn2The UPN.
Returns
TRUE if upn1 is an administrator for upn2 in realm.

◆ IsDecendantRealm()

bool SoftwareAndServices::Library::UPN::UpnDB::IsDecendantRealm ( UpnDbAuthHandle_t  id,
UpnDbRealmId_t  ParentRealm,
UpnDbRealmId_t  ChildRealm 
)

Determine if ChildRealm is a child or descendant of ParentRealm.

Parameters
idAn authenticated UPN handle.
ParentRealmThe parent realm to check.
ChildRealmThe child realm to check.
Returns
true if ChildRealm is a decedent of ParentRealm.

◆ IsMember()

bool SoftwareAndServices::Library::UPN::UpnDB::IsMember ( UpnDbAuthHandle_t  AuthHandle,
UpnDbMembershipId_t  listId,
UpnDbUpnId_t  upnId,
String expireTime 
)

Determine if a UPN-ID is a member of LIST-IDa.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
listIdThe ID of the list.
upnIdThe UPN ID to check.
expireTimeThe expire time to be returned.
Returns
TRUE if in list.

◆ IsSiteAdmin() [1/2]

bool SoftwareAndServices::Library::UPN::UpnDB::IsSiteAdmin ( UpnDbUpnId_t  upn) const

Determine if UPN is a site administrator.

Parameters
upnThe possible administrator id.
Returns
TRUE if UPN is a site administrator.

◆ IsSiteAdmin() [2/2]

bool SoftwareAndServices::Library::UPN::UpnDB::IsSiteAdmin ( UpnDbAuthHandle_t  AuthHandle) const

Determine if UPN is a site administrator.

Parameters
AuthHandleThe handle of an authenticated UPN being tested for administrator rights.
Returns
TRUE if UPN is a site administrator.

◆ Logout()

void SoftwareAndServices::Library::UPN::UpnDB::Logout ( UpnDbAuthHandle_t  AuthHandle)

Logout the user.

Parameters
AuthHandleThe authentication handle to logout. Fails if not the current authenticated UPN.

◆ PointsTotal()

unsigned int SoftwareAndServices::Library::UPN::UpnDB::PointsTotal ( UpnDbUpnId_t  upnId)

Get the UPN's total points.

Parameters
upnIdThe UPN who's points are to be fetched..
Returns
The UPN's total points.

◆ RemoveAddress()

bool SoftwareAndServices::Library::UPN::UpnDB::RemoveAddress ( UpnDbAuthHandle_t  AuthHandle,
UpnDbAddressId_t  addrId 
)

Delete an address Only the UPN and OR the realm administrator may delete this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
addrIdThe address to be deleted.
Returns
TRUE if removed.

◆ RemoveCc()

bool SoftwareAndServices::Library::UPN::UpnDB::RemoveCc ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
UpnDbCcId_t  cc 
)

Delete a Credit card.

Only the UPN and OR the realm administrator may delete this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID of the owner of the credit card.
ccThe Credit Card ID.
Returns
TRUE if removed.

◆ RemoveEmail()

bool SoftwareAndServices::Library::UPN::UpnDB::RemoveEmail ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
UpnDbEmailId_t  emailId 
)

Delete an email address.

Only the UPN and OR the realm administrator may delete this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID to apply the email info.
emailIdThe address to be deleted.
Returns
TRUE if removed.

◆ RemoveMembership()

bool SoftwareAndServices::Library::UPN::UpnDB::RemoveMembership ( UpnDbAuthHandle_t  AuthHandle,
UpnDbMembershipId_t  listId 
)

Remove a membership list.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
listIdThe handle the id.
Returns
TRUE if removed.

◆ RemovePref()

bool SoftwareAndServices::Library::UPN::UpnDB::RemovePref ( UpnDbAuthHandle_t  AppAuth,
UpnDbAuthHandle_t  UpnAuth,
UpnDbPrefId_t  prefId 
)

Remove a preference.

Parameters
AppAuthThe UPN authentication handle for the application.
UpnAuthThe UPN authentication handle for the user (UPN's authentication handle).
prefIdThe handle to the already fetched preference.
Returns
TRUE if removed.

◆ RemoveRealm()

bool SoftwareAndServices::Library::UPN::UpnDB::RemoveRealm ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realmToRemove,
bool  force = false 
)

Remove a realm.

WARNING: This removes all membership lists and UPNs in the realm.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
realmToRemoveThe parent realm id (zero == root)
forceIf the realm has child realms and 'force' is true, then all child realms, all their data including UPNs, addresses, and so on that are unique to those child realms will be forcefully deleted. This removes all child realms, and all of their child realms recursively.
Returns
TRUE if removed.

◆ RemoveRealmAdmin()

bool SoftwareAndServices::Library::UPN::UpnDB::RemoveRealmAdmin ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realm,
UpnDbUpnId_t  upnId 
)

Remove administrator rights from upnId.

. If the realm is the id of the 'root' node, then upnId will be removed as a site administrator..

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
realmThe REALM where upnId is no longer to be an administrator.
upnIdThe ID to make a realm or site administrator.
Returns
TRUE if upnId was removed as a realm or site administrator.

◆ RemoveUpnFromList()

bool SoftwareAndServices::Library::UPN::UpnDB::RemoveUpnFromList ( UpnDbAuthHandle_t  AuthHandle,
UpnDbMembershipId_t  list,
UpnDbUpnId_t  upn 
)

Remove UPN from realms membership list.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
listThe list to be removed from. If list is ZERO then member is removed from all lists.
upnThe UPN to remove.
Returns
TRUE if removed.

◆ RenameResourceId()

bool SoftwareAndServices::Library::UPN::UpnDB::RenameResourceId ( UpnDbAuthHandle_t  AuthHandle,
UpnDbResourceId_t  ResourceId,
const char *  NewName 
)

Rename a UpnDbResourceId_t This changes the name of an existing UpnDbResourceId_t For example, you could change the name from "home" to "Home", "any string".

Parameters
AuthHandleThe authentication handle of the the requestor.
ResourceIdThe UpnDbResourceId_t to change.
NewNameThe new name to use for ResourceId.
Returns
true if updated. Will return false when the AuthHandle does not have the authority to change the value.

◆ ReparentRealm()

bool SoftwareAndServices::Library::UPN::UpnDB::ReparentRealm ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realm,
UpnDbRealmId_t  newParent 
)

Reparent realm.

The adminUpn must be a site admin, or a realm admin for both realm and newParent.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
realmThe realm to re-parent.
newParentThe new parent realm id (zero == top level realm)
Returns
TRUE if moved.

◆ SaveLicenseInfo()

UpnDbLicenseId_t SoftwareAndServices::Library::UPN::UpnDB::SaveLicenseInfo ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  authRealmId,
UpnDbUpnId_t  upnId,
const String requestCode,
const String licenseKey,
const String product,
const String version,
bool  emailSent 
)

Store or Update license information.

If the same realmId, upnId, and requestCode exists in the database, update it.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
authRealmIdThe realm ID to authenticate against.
upnIdThe UPN associated with the license.
requestCodeThe request code to authenticate.
licenseKeyThe valid license key.
productThe product name being licensed.
versionThe product version being licensed.
emailSentSet to TRUE if the UPN was sent email.
Returns
The new ID for this license.

◆ SendEmail()

unsigned int SoftwareAndServices::Library::UPN::UpnDB::SendEmail ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  authRealmId,
UpnDbUpnId_t  fromUpnDbUpnId,
const String toListEmail,
const String toListNames,
const String ccListEmail,
const String ccListNames,
const String bccListEmail,
const String bccListNames,
const String errorsToList,
const String subject,
const std::vector< String *> &  otherHeaders,
const String body,
const std::vector< String *> &  attachments,
const std::vector< String *> &  attachMimeType 
)

Send email.

The email must be sent from an existing UPN or from an admin UPN. If the adminUPN is NULL, then the currently authenticated UPN will be used and fromUpnDbUpnId must match the currently authenticated UPN.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
authRealmIdThe realm to authenticate against.
fromUpnDbUpnIdThe UPN-ID that the email will be sent from.
toListEmailA list of email address in the TO: list.
toListNamesA list of names that go with the toListEmail list. If a name is not known, then is position in the list must be NULL.
ccListEmailA list of email address in the CC: list.
ccListNamesA list of names that go with the ccListEmail list. If a name is not known, then is position in the list must be NULL.
bccListEmailA list of email address to BCC
bccListNamesA list of names that go with the bccListEmail list. If a name is not known, then is position in the list must be NULL.
errorsToListA comma separated list of email address where email errors are sent. (Not honored by some older MTAs/MUAs).
subjectThe text to be used in the subject line of the email.
otherHeadersOther headers to be sent in the email.

Example "X-Foo: text for this header" as one entry. A colon (:) separates the header name from the header value.

Parameters
bodyThe plain text body to send.
attachmentsA NULL terminated array of attachments. There must be exactly one entry in this array for each entry in the 'attachMimeType' parameter.
attachMimeTypeA NULL terminated array of attachment MIME types. There must be exactly one entry in this array for each entry in the 'attachments' parameter.
Returns
(0) if successful, (1) if there is a problem with the data supplied in the call, or the SMTP error code returned from the remote email server. If the return code is greater than (1), call getErrorMessage() to get the error message.

◆ SetError() [1/2]

void SoftwareAndServices::Library::UPN::UpnDB::SetError ( SQL Sql,
SQL::SqlQueryId_t  qId = 0 
) const

Get and set the error.

Parameters
SqlThe SQL object.
qIdThe query ID used to make the query.

◆ SetError() [2/2]

void SoftwareAndServices::Library::UPN::UpnDB::SetError ( unsigned int  code,
const char *  msg 
) const

Record the error.

Parameters
codeThe error code.
msgThe error message.

◆ SetLDAP()

void SoftwareAndServices::Library::UPN::UpnDB::SetLDAP ( )

Future, use LDAP or ActiveDirectory.

Todo:
This will be in the next major release.

◆ SetMxHost()

void SoftwareAndServices::Library::UPN::UpnDB::SetMxHost ( const String mxHost)

Set the MX host to use when sending email.

Parameters
mxHostThe name of the MX host to use. NOTE: No error checking is done to see if it is valid!

◆ SetSpoken()

bool SoftwareAndServices::Library::UPN::UpnDB::SetSpoken ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
String FileName,
String MimeType,
String Extension 
)

Set the Spoken file.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN associated with the file.
FileNameThe file name of the spoken file.
MimeTypeThe MIME type of the spoken file.
ExtensionThe file extension. If not known, pass in an empty String.
Returns
true if saved.

◆ SetSQL()

void SoftwareAndServices::Library::UPN::UpnDB::SetSQL ( SQL sql,
const char *  Prefix = NULL 
)

Associate a database with this object.

Parameters
sqlThe already opened and authenticated database handle.
PrefixThe prefix to use for all tables in the database. If NULL, then 'sas_' will be used.

◆ UpdateAddress()

bool SoftwareAndServices::Library::UPN::UpnDB::UpdateAddress ( UpnDbAuthHandle_t  AuthHandle,
UpnDbAddressId_t  AddrId,
UpnDbResourceId_t  AddressType,
const String Street1,
const String Street2,
const String City,
const String State,
const String Zip,
UpnDbCountryCodeId_t  Country 
)

Update an existing address information for a UPN Only the UPN OR the realm administrator may add this information.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
AddrIdThe address ID to update.
AddressTypeThe name of this address (WORK, HOME, ...)
Street1Line one of the street address.
Street2Line two of the street address.
CityThe city (locality).
StateThe state (province).
ZipThe Zip Code (postal code).
CountryThe Country.
Returns
TRUE if updated.

◆ UpdatePref()

bool SoftwareAndServices::Library::UPN::UpnDB::UpdatePref ( UpnDbAuthHandle_t  AppAuth,
UpnDbAuthHandle_t  UpnAuth,
UpnDbPrefId_t  PrefId,
const char *  PrefValue 
)

Update an existing preference with a new value.

Parameters
AppAuthThe UPN authentication handle for the application.
UpnAuthThe UPN authentication handle for the user (UPN's authentication handle).
PrefIdThe handle to the already fetched preference.
PrefValueThe new value.
Returns
TRUE if updated.

◆ UpdateRealm()

bool SoftwareAndServices::Library::UPN::UpnDB::UpdateRealm ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmRecord Rec 
)

Update the realm record in the database.

Parameters
AuthThe handle of the currently authenticated UPN. Only the a site or realm administrator my update the UPN record.

To update a UPN record, call GetRealmRecord(), update the values as needed and described below, then call UpdateRealm():

An existing Realm ID (Rec.Id) can never be changed. The Realm ID is the key that will be updated.

Rec.ParentId can only be changed with AuthHandle is for a site administrator of both the old and new realms, or when AuthHandle is a site administrator.

Rec.Created will always be ignored in an update. You can not update when a REALM was created.

Rec.CanHaveChildren, set this to true to allow this realm to have sub-realms. When false, this realm may not have sub-realms. If the realm already has sub-realms, and the record is set to false, this method will fail.

Rec.CanHaveUpns, set this to allow the realm to have UPNs.

Rec.CanRemove: When true, this realm may be removed. When false, this realm can not be removed with the libSaSUpnDb libraries. This field will be ignored when AuthHandle is not a site administrator.

Rec.Description: Optional description of the realm that informs the reader about this realm.

Rec.Disabled: When true, no UPN will be allowed to login using the libSaSUpnDb libraries. This disables the entire realm. When false, UPNs may login to this realm.

Returns
true when the record has been updated. On failure call this->GetError() to get any error.
See also
SoftwareAndServices::Library::Common::Error

◆ UpdateRealmChild()

bool SoftwareAndServices::Library::UPN::UpnDB::UpdateRealmChild ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  toUpdateId,
bool  canHaveChild,
bool  force = false 
)

Alter the canHaveChild property of a realm.

If the status is being changed from can have child realms, to can NOT have child realms, the child realms must first be removed. Unless the 'force' option is true.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
toUpdateIdThe ID of the realm to change.
canHaveChildIf TRUE, this realm can be the parent of other realms.
forceOnly used when 'canHaveChild' is false. If the realm already has child realms and 'force' is true, then all child realms, all their data including UPNs, addresses, and so on that are unique to those child realms will be forcefully deleted. This removes all child realms, and all of their child realms recursively.
Returns
TRUE if successful. Returns FALSE if authentication fails. And returns FALSE if existing child realms exist and force is false.

◆ UpdateUpn() [1/2]

bool SoftwareAndServices::Library::UPN::UpnDB::UpdateUpn ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
const String namePrefix,
const String nameFirst,
const String nameMiddle,
const String nameLast,
const String nameSuffix 
)

Update UPN name.

Only the UPN OR the realm administrator may update this information.

Parameters
upnIdThe UPN id to be updated.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID to be updated.
namePrefix(Mr. Ms. ...)
nameFirstThe UPN's first name.
nameMiddleThe UPN's middle name.
nameLastThe UPN's last name.
nameSuffix(Jr. Sr. 3rd ...)
Returns
TRUE if successful.

◆ UpdateUpn() [2/2]

bool SoftwareAndServices::Library::UPN::UpnDB::UpdateUpn ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
const char *  namePrefix,
const char *  nameFirst,
const char *  nameMiddle,
const char *  nameLast,
const char *  nameSuffix 
)

Update UPN name.

Only the UPN OR the realm administrator may update this information.

Parameters
upnIdThe UPN id to be updated.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID to be updated.
namePrefix(Mr. Ms. ...)
nameFirstThe UPN's first name.
nameMiddleThe UPN's middle name.
nameLastThe UPN's last name.
nameSuffix(Jr. Sr. 3rd ...)
Returns
TRUE if successful.

◆ UpdateUpnInList()

bool SoftwareAndServices::Library::UPN::UpnDB::UpdateUpnInList ( UpnDbAuthHandle_t  AuthHandle,
UpnDbMembershipId_t  list,
UpnDbUpnId_t  upn,
const String expire 
)

Update the expire time for UPN from realms membership list.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
listThe list to be added to.
upnThe UPN to add
expireIf not NULL, the expire time (DDMMYYYY) or (DDMMYYYYTHHMMSS)
Returns
TRUE if updated.

◆ UrlViewed()

unsigned int SoftwareAndServices::Library::UPN::UpnDB::UrlViewed ( UpnDbUpnId_t  upnId,
const String urlVisited 
)

Track that upId viewed urlVisited.

Parameters
upnIdThe UPN to be logged.
urlVisitedThe URL to log.
Returns
The UPN's total points.

◆ ValidAuthHandle()

bool SoftwareAndServices::Library::UPN::UpnDB::ValidAuthHandle ( UpnDbAuthHandle_t  AuthHandle) const

Validate the AuthHandle_t, the user must be authenticated.

Parameters
AuthHandleAn active authentication handle.
Returns
TRUE if authenticated and valid.

◆ VerifyPassword() [1/2]

bool SoftwareAndServices::Library::UPN::UpnDB::VerifyPassword ( UpnDbAuthHandle_t  AuthHandle,
const char *  Password 
)

Check to see if the caller knows the password for Auth.

This would be called in critical sections, such as changing the UPN data, in order to verify the intended UPN is changing their own data.

Parameters
AuthHandleThe authentication handle to check.
PasswordThe attempted password.
Returns
true if they match, else a random amount of sleep time will proceed the false return.

◆ VerifyPassword() [2/2]

bool SoftwareAndServices::Library::UPN::UpnDB::VerifyPassword ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  ForUpnId,
const char *  Password 
)

Check to see if the caller knows the password for Auth.

This would be called in critical sections, such as changing the UPN data, in order to verify the intended UPN is changing their own data.

Parameters
AuthHandleThe authentication handle to check. Must be to a site or realm administrator.
ForUpnIdThe UPN ID to check the password for.
PasswordThe attempted password.
Returns
true if they match, else a random amount of sleep time will proceed the false return.

Member Data Documentation

◆ _ErrorCode

unsigned int SoftwareAndServices::Library::UPN::UpnDB::_ErrorCode
mutableprotected

The last error code.

Definition at line 2551 of file UpnDB.hpp.

◆ _ErrorMessage

const char* SoftwareAndServices::Library::UPN::UpnDB::_ErrorMessage
mutableprotected

The last error message.

Definition at line 2556 of file UpnDB.hpp.

◆ _GUID

const char* SoftwareAndServices::Library::UPN::UpnDB::_GUID
staticprotected

The GUID for the currently authenticated application.

Definition at line 2533 of file UpnDB.hpp.

◆ _OurSql

bool SoftwareAndServices::Library::UPN::UpnDB::_OurSql
protected

If we allocated the _sql variable this will be TRUE.

Definition at line 2523 of file UpnDB.hpp.

◆ _Prefix

const char* SoftwareAndServices::Library::UPN::UpnDB::_Prefix
protected

The database object prefix to use for all SQL objects.

Definition at line 2528 of file UpnDB.hpp.

◆ _Realm

UpnDbRealmId_t SoftwareAndServices::Library::UPN::UpnDB::_Realm
protected

REALM ID of the last authenticated UPN.

Definition at line 2546 of file UpnDB.hpp.

◆ _Sql

SQL* SoftwareAndServices::Library::UPN::UpnDB::_Sql
protected

The SQL handle to the database being used.

Definition at line 2518 of file UpnDB.hpp.

◆ _Upn

UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDB::_Upn
protected

ID of the last authenticated UPN.

Definition at line 2541 of file UpnDB.hpp.


The documentation for this class was generated from the following file: