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

A record of an individual UPN (person) More...

#include <SaS/UpnDb/UpnDB.hpp>

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

Public Member Functions

 UpnDbUpnRecord ()
 UpnDbUpnRecord - Defaul Constructor. More...
 
virtual ~UpnDbUpnRecord ()
 UpnDbUpnRecord - Destructor. More...
 
bool Add (UpnDbAuthHandle_t Auth)
 Add this object as a new record. More...
 
bool Remove (UpnDbAuthHandle_t Auth)
 Remove this record from the UPN database. More...
 
bool Update (UpnDbAuthHandle_t Auth) const
 Update this record. More...
 

Static Public Member Functions

static UpnDbUpnId_t AddUpn (UpnDbAuthHandle_t AuthHandle, const char *Password, UpnDbUpnRecord &Rec)
 Add a new UPN from a UpnDbUpnRecord object. More...
 
static UpnDbUpnId_t AddUpn (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t RealmId, const char *Upn, const char *Password, UpnDbUpnId_t PrimaryUpnId, UpnDbResource_t Type=UpnDbResourceIdPerson_t)
 Add a new UPN, where the additional information is stored with another UPN-ID as the primary UPN. More...
 
static UpnDbUpnId_t AddUpn (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t RealmId, const String &Upn, const String &Password, const String &NamePrefix, const String &NameFirst, const String &NameMiddle, const String &NameLast, const String &NameSuffix, UpnDbResource_t Type=UpnDbResourceIdPerson_t)
 Add a new UPN. More...
 
static bool GetUpn (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, String &namePrefix, String &nameFirst, String &nameMiddle, String &nameLast, String &nameSuffix)
 Get UPN name. More...
 
static UpnDbUpnId_t GetUpnId (UpnDbAuthHandle_t AuthHandle)
 Get the UPN id of the AuthHandle_t. More...
 
static UpnDbUpnId_t GetUpnId (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realm, const String &upn)
 Get a UPNs ID. More...
 
static UpnDbUpnId_t GetUpnId (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realm, const char *upn)
 Get a UPNs ID. More...
 
static bool GetUpnRecord (UpnDbAuthHandle_t Auth, UpnDbUpnRecord &Results, UpnDbRealmId_t realm, const String &upn)
 Get a UPN RECORD. More...
 
static bool GetUpnRecord (UpnDbAuthHandle_t Auth, UpnDbUpnRecord &Results, UpnDbRealmId_t realm, const char *upn)
 Get a UPN RECORD. More...
 
static bool GetUpns (UpnDbAuthHandle_t AuthHandle, UpnDbRealmId_t realm, std::vector< UpnDbUpnId_t > &Answers)
 Get the nTh UPN id. More...
 
static bool GetUpns (UpnDbAuthHandle_t AuthHandle, std::vector< UpnDbUpnRecord *> &Results, UpnDbRealmId_t realmId)
 If realmAdmin is a site or realm administrator, return a list of UPNs for the named realm. More...
 
static bool GetUpnValue (UpnDbAuthHandle_t Auth, String &Results, UpnDbUpnId_t upnId)
 Get the UPN value (user@.nosp@m.exam.nosp@m.ple.c.nosp@m.om) given a UPN ID. More...
 
static bool RemoveUpn (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId)
 Remove a UPN. More...
 
static bool UpdateUpn (UpnDbAuthHandle_t Auth, UpnDbUpnRecord &Rec, const char *NewPw=NULL)
 Update a UpnDbUpnRecord. More...
 
static bool UpdateUpnPassword (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t UpnId, const String &OldPassword, const String &NewPassword)
 Update UPN password. More...
 
static bool UpdateUpnValue (UpnDbAuthHandle_t AuthHandle, UpnDbUpnId_t upnId, const String &newValue)
 Update UPN value. More...
 
static UpnDbUpnId_t UpnExists (UpnDbAuthHandle_t Auth, UpnDbRealmId_t realm, const char *upn)
 Test if UPN exists in realm. More...
 
static UpnDbUpnId_t UpnExists (UpnDbAuthHandle_t Auth, UpnDbRealmId_t realm, const String &upn)
 Test if UPN exists in realm. More...
 

Detailed Description

A record of an individual UPN (person)

Definition at line 74 of file UpnDbUpnRecord.hpp.

Constructor & Destructor Documentation

◆ UpnDbUpnRecord()

SoftwareAndServices::Library::UPN::UpnDbUpnRecord::UpnDbUpnRecord ( )

UpnDbUpnRecord - Defaul Constructor.

◆ ~UpnDbUpnRecord()

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

UpnDbUpnRecord - Destructor.

Member Function Documentation

◆ Add()

bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::Add ( UpnDbAuthHandle_t  Auth)
virtual

Add this object as a new record.

Parameters
AuthThe authentication handle to use.
Returns
true if added.

Implements SoftwareAndServices::Library::UPN::UpnDbRecord.

◆ AddUpn() [1/3]

static UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDbUpnRecord::AddUpn ( UpnDbAuthHandle_t  AuthHandle,
const char *  Password,
UpnDbUpnRecord Rec 
)
static

Add a new UPN from a UpnDbUpnRecord object.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
PasswordThe new UPN's password.
RecA filled in UpnDbUpnRecord object.

Rec.Upn Fill in with the new UPN name.

Rec.Id will be ignored when adding. Will be filled in with zero (0) on failure, or the new UpnDbUpnId_t on success.

Rec.CertId. Set to the correct certificate ID number, or one (1) if no certificate. A value of zero (0) will cause AddUpn to fail.

Rec.IsRealmAdmin When true, the new UPN will be a realm administrator. When IsAdmin(AuthHandle) returns false and when IsSiteAdmin(AuthHandle) returns false, this field will be ignored and the new UPN will not be a realm administrator.

Rec.IsSiteAdmin When true, the new UPN will be a site administrator. When IsSiteAdmin(AuthHandle) returns false, this field will be ignored and the new UPN will not be a site administrator.

Rec.RealmId The ID of the realm to add this new UPN to.

Note
Rec.RealmId + Rec.Upn must be unique.

Rec.ResourceId Set to the type of UPN to be added.

Rec.CanRemove When false, the libSaSUpnDB library will not be able to remove this UPN from the database. When IsSiteAdmin(AuthHandle) returns false, this field will be ignored.

Rec.Disabled When true, this UPN will not be able to login using the libSaSUpnDb library.

Rec.PrimaryUpnId Set to the UPN-ID of the UPN that is related, that has the detail information (name, address, phone, ...). Or set to zero to indicate this is the primary UPN for this entity. Upon sucessful completion of this method it will be set to Rec.Id.

Returns
The new UPNs ID or zero on error. Also returns zero any memeber of Rec is invalid.

◆ AddUpn() [2/3]

static UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDbUpnRecord::AddUpn ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  RealmId,
const char *  Upn,
const char *  Password,
UpnDbUpnId_t  PrimaryUpnId,
UpnDbResource_t  Type = UpnDbResourceIdPerson_t 
)
static

Add a new UPN, where the additional information is stored with another UPN-ID as the primary UPN.

This allows one entity to have multiple UPNs. Possibly in multiple realms.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
RealmIdThe REALM of the new UPN.
UpnThe User Principal Name (UPN).
PasswordThe new UPN's password. Must not be NULL,
PrimaryUpnIdThis is the UPN-ID of an existing UPN where the name, address, phone, etc, can be found.
TypeIf the UPN is a PERSON, PLACE, or THING. defaults to person.
Returns
The new UPNs ID or zero on error. Also returns zero when PrimaryUpnId does not exist.

◆ AddUpn() [3/3]

static UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDbUpnRecord::AddUpn ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  RealmId,
const String &  Upn,
const String &  Password,
const String &  NamePrefix,
const String &  NameFirst,
const String &  NameMiddle,
const String &  NameLast,
const String &  NameSuffix,
UpnDbResource_t  Type = UpnDbResourceIdPerson_t 
)
static

Add a new UPN.

Add this UPN as a primary UPN.

A primary UPN is where an entities name, phone, address, etc information is stored.

An entity may have multiple UPNs, each with a unique 'upn' value.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
RealmIdThe REALM of the new UPN.
UpnThe User Principal Name (UPN).
PasswordThe new UPN's password. Must not be NULL.
NamePrefix(Mr. Ms. ...)
NameFirstThe UPN's first name.
NameMiddleThe UPN's middle name.
NameLastThe UPN's last name.
NameSuffixnameSuffix (Jr. Sr. 3rd ...)
TypeIf the UPN is a PERSON, PLACE, or THING. defaults to person.
Returns
The new UPNs ID or zero on error.

◆ GetUpn()

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpn ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
String &  namePrefix,
String &  nameFirst,
String &  nameMiddle,
String &  nameLast,
String &  nameSuffix 
)
static

Get UPN name.

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

Parameters
upnIdThe UPN id to be fetched.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID to be fetched.
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.

◆ GetUpnId() [1/3]

static UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpnId ( UpnDbAuthHandle_t  AuthHandle)
static

Get the UPN id of the AuthHandle_t.

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

◆ GetUpnId() [2/3]

static UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpnId ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realm,
const String &  upn 
)
static

Get a UPNs ID.

This performs no other action other than to get the ID. It grants no privileges at all.

Parameters
AuthHandleThe handle from a successful authentication.
realmThe realm to be searched. For non-administrators this must match the UPN's realm.
upnThe UPN of a user on the system.
Returns
The ID or zero if UPN does not exist.

◆ GetUpnId() [3/3]

static UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpnId ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realm,
const char *  upn 
)
static

Get a UPNs ID.

This performs no other action other than to get the ID. It grants no privileges at all.

Parameters
AuthHandleThe handle from a successful authentication.
realmThe realm to be searched. For non-administrators this must match the UPN's realm.
upnThe UPN of a user on the system.
Returns
The ID or zero if UPN does not exist.

◆ GetUpnRecord() [1/2]

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpnRecord ( UpnDbAuthHandle_t  Auth,
UpnDbUpnRecord Results,
UpnDbRealmId_t  realm,
const String &  upn 
)
static

Get a UPN RECORD.

Parameters
AuthThe handle to the currently authenticated UPN.
ResultsA pointer to a UpnDbUpnRecord that will be filled in if return value is TRUE.
realmThe realm to be searched. For non-administrators this must match the UPN's realm.
upnThe UPN of a user on the system.
Returns
TRUE when found and Results are filled in.

◆ GetUpnRecord() [2/2]

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpnRecord ( UpnDbAuthHandle_t  Auth,
UpnDbUpnRecord Results,
UpnDbRealmId_t  realm,
const char *  upn 
)
static

Get a UPN RECORD.

Parameters
AuthThe handle to the currently authenticated UPN.
ResultsA pointer to a UpnDbUpnRecord that will be filled in if return value is TRUE.
realmThe realm to be searched. For non-administrators this must match the UPN's realm.
upnThe UPN of a user on the system.
Returns
TRUE when found and Results are filled in.

◆ GetUpns() [1/2]

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpns ( UpnDbAuthHandle_t  AuthHandle,
UpnDbRealmId_t  realm,
std::vector< UpnDbUpnId_t > &  Answers 
)
static

Get the nTh UPN id.

Only the realm administrator can make this call.

Parameters
realmThe realm to be searched. If NULL, then all realms will be searched.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
AnswersA std::vector<UpnDbUpnId_t> of matches.
Returns
TRUE if authenticated and at least one answer.

◆ GetUpns() [2/2]

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpns ( UpnDbAuthHandle_t  AuthHandle,
std::vector< UpnDbUpnRecord *> &  Results,
UpnDbRealmId_t  realmId 
)
static

If realmAdmin is a site or realm administrator, return a list of UPNs for the named realm.

Parameters
ResultsA reference to a vector of UpnDbUpnRecord objects.
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
realmIdThe REALM ID to search for the UPN list.
Returns
TRUE if any are found.

◆ GetUpnValue()

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::GetUpnValue ( UpnDbAuthHandle_t  Auth,
String &  Results,
UpnDbUpnId_t  upnId 
)
static

Get the UPN value (user@.nosp@m.exam.nosp@m.ple.c.nosp@m.om) given a UPN ID.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
ResultsA pointer to a String where the results are appended.
upnIdThe UPN id to be fetched.
Returns
TRUE if a match is found and added to Results.

◆ Remove()

bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::Remove ( UpnDbAuthHandle_t  Auth)
virtual

Remove this record from the UPN database.

Parameters
AuthThe authentication handle to use.
Returns
true if removed.

Implements SoftwareAndServices::Library::UPN::UpnDbRecord.

◆ RemoveUpn()

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::RemoveUpn ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId 
)
static

Remove a UPN.

Only the UPN OR the realm administrator may remove a UPN.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
upnIdThe UPN ID to be removed.
Returns
TRUE if removed.

◆ Update()

bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::Update ( UpnDbAuthHandle_t  Auth) const
virtual

Update this record.

Parameters
AuthThe authentication handle to use.
Returns
true if updated.

Implements SoftwareAndServices::Library::UPN::UpnDbRecord.

◆ UpdateUpn()

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::UpdateUpn ( UpnDbAuthHandle_t  Auth,
UpnDbUpnRecord Rec,
const char *  NewPw = NULL 
)
static

Update a UpnDbUpnRecord.

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

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

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

The CERT ID (Rec.CertId) will be ignored in an update. Use UpdateUpnCertificate() to change a UPNs certificates.

Rec.IsRealmAdmin, when true, will make the UPN a realm administrator.

When Auth is a site administrator, and Rec.IsSiteAdmin is true, then UPN will be set to a site administrator.

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

Rec.RealmId will be checked and when Auth is a realm administrator, and not a realm administrator in the old and new realms, this will cause the entire UpdateUpn() call to fail.

Rec.CanRemove will be ignored when Auth is not a site administrator. Rec.Disabled may be what you need.

Parameters
AuthThe handle to a currently authenticated realm or site administrator.
RecThe updated UpnDbUpnRecord. This record will used to update the database entries.
NewPwWhen non-NULL, the UPN password will be changed to NewPw.
Returns
true when saved, false means nothing happened. On failure call this->GetError() to get any error.
See also
UpdateUpnCertificate()
SoftwareAndServices::Library::Common::Error

◆ UpdateUpnPassword()

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::UpdateUpnPassword ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  UpnId,
const String &  OldPassword,
const String &  NewPassword 
)
static

Update UPN password.

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.
OldPasswordThe old password for the account. If the adminUpn supplied in the call is a realm administrator then 'oldPassword' does not need to be supplied. If the adminUpn supplied in the call is the UPN changing their own password, then 'oldPassword' MUST BE supplied.
NewPasswordThe new password to be used for the account. Must not be NULL.
Returns
TRUE if the password was changed. When oldPassword is supplied a failure (false) means the oldPassword did not match.

◆ UpdateUpnValue()

static bool SoftwareAndServices::Library::UPN::UpnDbUpnRecord::UpdateUpnValue ( UpnDbAuthHandle_t  AuthHandle,
UpnDbUpnId_t  upnId,
const String &  newValue 
)
static

Update UPN value.

This is used when the UPN value needs to be updated (user1.nosp@m.@foo.nosp@m..com changes to other.nosp@m.-use.nosp@m.r@fee.nosp@m..com). 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.
newValueThe new UPN value.
Returns
TRUE if changed. A FALSE result means that the newValue is already in use.

◆ UpnExists() [1/2]

static UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDbUpnRecord::UpnExists ( UpnDbAuthHandle_t  Auth,
UpnDbRealmId_t  realm,
const char *  upn 
)
static

Test if UPN exists in realm.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
realmThe realm to check.
upnThe UPN to check.
Returns
The UPN ID if found, else zero.

◆ UpnExists() [2/2]

static UpnDbUpnId_t SoftwareAndServices::Library::UPN::UpnDbUpnRecord::UpnExists ( UpnDbAuthHandle_t  Auth,
UpnDbRealmId_t  realm,
const String &  upn 
)
static

Test if UPN exists in realm.

Parameters
AuthHandleThe UPN handle of an administrator. Or the administrator of a parent realm.
realmThe realm to check.
upnThe UPN to check.
Returns
The UPN ID if found, else zero.

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