Notification

rkProxy —: the Proxy with which this object will be associated, providing access to a channel and validation against the channel's subject tree and notification type
rkstrSubject —: a subject for the notification
throws —: Notification throws an InvalidSubjectException if the specified subject is invalid for the underlying channel.; Notification throws an InvalidNotificationException if there is a problem setting up the notification message.

Notification by ChannelInfo

Notification(
const ChannelInfo& rkChannelInfo,
const PCSmallString& rkstrSubject,
const PC_CHAR* kszAttrVals)
throw( InvalidSubjectException,
InvalidNotificationException)

Constructs a Notification object from a subject string and associates this notification with a ChannelInfo.

rkChannelInfo —: the ChannelInfo with which this object will be associated, providing access to a channel and validation against the channel's subject tree and notification type
rkstrSubject —: a subject for the notification
kszAttrVals —: a comma-separated sequence of attribute assignments of the form name=(type)value
throws —: Notification throws an InvalidSubjectException if the specified subject is invalid for the channel.; Notification throws an InvalidNotificationException if the specified attribute assignments are syntactically incorrect or are inconsistent with the notification type of the channel, or if there is a problem setting up the notification message.

Notification copy

Notification(const Notification& rkNotification) throw(InvalidNotificationException)

Constructs a copy of a Notification object.

rkNotification —: the notification to be copied
throws —: copy throws an InvalidNotificationException if the attempt to copy was unsuccessful

Notification assignment

Notification& operator=(
const Notification& rNotification) throw( InvalidNotificationException)

Assigns one Notification object to another.

rNotification —: the notification to be assigned
throws —: assignment throws an InvalidNotificationException if the attempt to assign was unsuccessful.

Destructor

~Notification()

Frees up resources that were allocated for this object.

Methods

Subject

const PCSmallString& Subject()

Returns the subject of the notification.

SubjectMapping

vector<PC_UINT16> SubjectMapping()

The integer mapping of the subject associated with the notification.

void Print()

Prints a text rendering of the notification's contents on the standard output stream

SetPredefinedAttr — Generic

by name

virtual void SetPredefinedAttr(
const PCSmallString& rkstrName,
const void* pkVal,
PC_TypeCode idTypeCode,
PC_UINT unSizeIfArray = PC_ATTR_SIZE_ARG_DEFAULT)
throw(InvalidNotificationException)

Sets the values of a specified attribute of the notification, identified by its name.

rkstrName —: the name of the predefined attribute whose value is to be set
pkVal —: an untyped pointer to a variable containing the value of the specified attribute (or the address of its first element, if it is a string or array value); the caller must ensure that the variable is of the correct type
idTypeCode —: the type code of pkVal
unSizeIfArray —: if idTypeCode designates an array type, then this parameter is the number of elements in the array name
throws —: setPredefinedAttr throws an InvalidNotificationException if rkstrName is not the name of a predefined attribute, or if ridTypeCode is not the same as the type of the attribute as determined by the notification type of the channel.

by position

Sets the values of a specified attribute of the notification, identified by its position.

virtual void SetPredefinedAttr(
PC_UINT unPos,
const void* pkVal,
PC_TypeCode idTypeCode,
PC_UINT unSize = PC_ATTR_SIZE_ARG_DEFAULT)
throw( InvalidNotificationException)

unPos —: the position of the predefined attribute whose value is to be set, with respect to the sequence of predefined attributes defined by the notification type of the underlying channel, starting with 0
pkVal —: the value to be assigned to the attribute
idTypeCode —: the type code of pkVal
unSizeIfArray —: if idTypeCode designates an array type, then this parameter is the number of elements in the array
throws —: SetPredefinedAttr throws an InvalidNotificationException if there is no predefined attribute in the specified position, or if the type of val is not the same as the type of the attribute as determined by the notification type of the channel, or, in the case of floating-point types, if val is a NaN.

GetPredefinedAttr — Generic

by name

virtual void GetPredefinedAttr(
const PCSmallString& rkstrName,
void*& rpVal,
PC_TypeCode idTypeCode) throw( InvalidNotificationException)

virtual void GetPredefinedAttr(
const PCSmallString& rkstrName,
void*& rpVal,
PC_TypeCode idTypeCode,
PC_UINT& runSizeIfArray) throw( InvalidNotificationException)

Returns the value of a predefined attribute of this object, identified by name. The first signature returns nonarrayed attributes values; the second signature returns an array of values.

rkstrName —: the name of the predefined attribute whose value is to be returned
rpVal —: variable to hold an untyped pointer to the value of the specified attribute, or for array-valued attributes to hold an untyped copy of the array pointer itself
idTypeCode —: the type code of rpVal
runSizeIfArray —: if idTypeCode designates an array type, then this parameter is the number of elements in the array name
returns —: the value of a predefined attribute of this object, identified by its name
throws —: SetPredefinedAttr throws an InvalidNotificationException if rkstrName is not the name of a predefined attribute, or if ridTypeCode is not the same as the type of the attribute as determined by the notification type of the channel.

by position

virtual void GetPredefinedAttr(
PC_UINT unPos,
void*& rpVal,
PC_TypeCode idTypeCode) throw( InvalidNotificationException)

virtual void GetPredefinedAttr(
PC_UINT unPos,
void*& rpVal,
PC_TypeCode idTypeCode,
PC_UINT& runSizeIfArray) throw( InvalidNotificationException)

Returns the value of a predefined attribute of this object, identified by position. The first signature returns nonarrayed attributes values; the second signature returns an array of values.

unPos —: the position of the predefined attribute whose value is to be returned, with respect to the sequence of predefined attributes defined by the notification type of the channel, starting with 0
rpVal —: variable to hold an untyped pointer to the value of the specified attribute, or for array-valued attributes to hold an untyped copy of the array pointer itself
idTypeCode —: the type code of rpVal
runSizeIfArray —: if idTypeCode designates an array type, then this parameter is the number of elements in the array name
returns —: an untyped pointer to the value of the specified attribute
throws —: GetPredefinedAttr throws an InvalidNotificationException if there is no predefined attribute in the specified position.

SetPredefinedAttr — Typed

by name

void SetPredefinedAttr(
const PC_SmallString& rkstrName,
type val)
throw( InvalidNotificationException)

void SetPredefinedAttr(
const PC_SmallString& rkstrName,
type* val,
PC_UINT unSize)
throw( InvalidNotificationException)

Sets the value of a predefined attribute of this object, identified by its name. The first signature sets nonarrayed attributes values; the second signature sets an array of values.

As delineated below, this method is overloaded on all allowed types for parameter val.

SetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_CHAR val)

SetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_LONG val)

SetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_DOUBLE val)

SetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_CHAR_ARRAY val)

SetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_LONG_ARRAY val,
PC_UINT unSize)

SetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_DOUBLE_ARRAY val,
PC_UINT unSize)

SetPredefinedAttrByteArray
(const PCSmallString& rkstrName,
const PC_BYTE_ARRAY val,
PC_UINT unSize)

rkstrName —: the name of the predefined attribute whose value is to be set
type —: the data type of the attribute
val —: an untyped pointer to a variable containing the value of the specified attribute (or the address of its first element, if it is a string or array value); the caller must ensure that the variable is of the correct type
unSize —: the number of elements in val
throws —: SetPredefinedAttr throws an InvalidNotificationException if rkstrName is not the name of a predefined attribute, or if the type of val is not the same as the type of the attribute as determined by the notification type of the channel, or, in the case of floating-point types, if val is a NaN.

by position

void SetPredefinedAttr(
const PC_UINT unPos,
type val)
throw( InvalidNotificationException)

void SetPredefinedAttr(
const PC_UINT unPos,
type* val,
PC_UINT unSize)
throw( InvalidNotificationException)

Sets the value of a predefined attribute of this object, identified by its position. The first signature returns nonarrayed attributes values; the second signature returns an array of values.

As delineated below, this method is overloaded on all allowed types for parameter val.

SetPredefinedAttr(
const PC_UINT unPos,
PC_CHAR val)

SetPredefinedAttr(
const PC_UINT unPos,
PC_LONG val)

SetPredefinedAttr(
const PC_UINT unPos,
PC_DOUBLE val)

SetPredefinedAttr(
const PC_UINT unPos,
PC_CHAR_ARRAY val)

SetPredefinedAttr(
const PC_UINT rkstrName,
PC_LONG_ARRAY val,
PC_UINT unSize)

SetPredefinedAttr(
const PC_UINT rkstrName,
PC_DOUBLE_ARRAY val,
PC_UINT unSize)

SetPredefinedAttrByteArray
(PC_UINT unPos,
const PC_BYTE_ARRAY val,
PC_UINT unSize)

unPos —: the position of the predefined attribute whose value is to be set, with respect to the sequence of predefined attributes defined by the notification type of the underlying channel, starting with position 0
type —: the data type of the attribute
val —: the value to be assigned to the attribute
unSize —: the number of elements in val
throws —: SetPredefinedAttr throws an InvalidNotificationException if rkstrName is not the name of a predefined attribute, or if the type of val is not the same as the type of the attribute as determined by the notification type of the channel, or, in the case of floating-point types, if val is a NaN.

GetPredefinedAttr — Typed

by name

void GetPredefinedAttr(
const PC_SmallString& rkstrName,
type& rVal)
throw( InvalidNotificationException)

void GetPredefinedAttr(
const PC_SmallString& rkstrName,
type* rVal,
PC_UINT& runSize)
throw( InvalidNotificationException)

Returns the value of a predefined attribute of this object, identified by its name. The first signature returns nonarrayed attributes values; the second signature returns an array of values.

As delineated below, this method is overloaded on all allowed types for parameter val.

GetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_CHAR& rVal)

GetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_LONG& rVal)

GetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_DOUBLE& rVal)

GetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_CHAR_ARRAY& rVal)

GetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_LONG_ARRAY rVal,
PC_UINT& runSize)

GetPredefinedAttr(
const PC_SmallString& rkstrName,
PC_DOUBLE_ARRAY rVal,
PC_UINT& runSize)

GetPredefinedAttrByteArray
(const PCSmallString& rkstrName,
PC_BYTE_ARRAY& rVal,
PC_UINT& runSize)

rkstrName —: the name of the predefined attribute whose value is to be returned
type —: the data type of the attribute
rVal —

the value of the specified attribute

runSize —: the number of elements in rVal
throws —: GetPredefinedAttr throws an InvalidNotificationException if rkstrName is not the name of a predefined attribute, or if the type of val is not the same as the type of the attribute as determined by the notification type of the channel.

by position

void GetPredefinedAttr(
const PC_UINT unPos,
type& rVal)
throw( InvalidNotificationException)

void GetPredefinedAttr(
const PC_UINT unPos,
type* rVal)
throw( InvalidNotificationException)

Returns the value of a predefined attribute of this object, identified by its position. The first signature returns nonarrayed attributes values; the second signature returns an array of values.

As delineated below, this method is overloaded on all allowed types for parameter val.

GetPredefinedAttr(
const PC_UINT unPos,
PC_CHAR& rVal)

GetPredefinedAttr(
const PC_UINT unPos,
PC_LONG& rVal)

GetPredefinedAttr(
const PC_UINT unPos,
PC_DOUBLE& rVal)

GetPredefinedAttr(
const PC_UINT unPos,
PC_CHAR_ARRAY& rVal)

GetPredefinedAttr(
const PC_UINT unPos,
PC_LONG_ARRAY& rVal,
PC_UINT& runSize)

GetPredefinedAttr(
const PC_UINT unPos,
PC_DOUBLE_ARRAY& rVal,
PC_UINT& runSize)

GetPredefinedAttrByteArray
(PC_UINT unPos,
PC_BYTE_ARRAY& rVal,
PC_UINT& runSize)

unPos —: the position of the predefined attribute whose value is to be returned, with respect to the sequence of predefined attributes defined by the notification type of the channel, starting with 0
type —: the data type of the attribute
rVal —

the value of the specified attribute

runSize —: the number of elements in rVal
throws —: GetPredefinedAttr throws an InvalidNotificationException if rkstrName is not the name of a predefined attribute, or if the type of val is not the same as the type of the attribute as determined by the notification type of the channel.

AddDiscretionaryAttr — Generic

virtual void AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
const void* pkVal,
PC_TypeCode idTypeCode,
PC_UINT unSizeIfArray = PC_ATTR_SIZE_ARG_DEFAULT)
throw( InvalidNotificationException)

Sets the value of a discretionary attribute of this object.

rkstrName —: the name of the discretionary attribute whose value is to be set
pkVal —: an untyped pointer to a variable containing the value of the specified attribute (or the address of its first element, if it is a string or array value)
idTypeCode —: the type code of pkVal
unSizeIfArray —: if idTypeCode designates an array type, then this parameter is the number of elements in the array
throws —: AddDiscretionaryAttr throws an InvalidNotificationException if rkstrName belongs to a predefined attribute.

AddDiscretionaryAttr — Typed

void AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
type val)
throw( InvalidNotificationException)

void AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
const type* val,
PC_UINT unSize)
throw( InvalidNotificationException)

Sets the value of a discretionary attribute of this object, identified by its name. The first signature sets nonarrayed attributes values; the second signature sets an array of values.

As delineated below, this method is overloaded on all allowed types for parameter val.

AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
PC_CHAR val)

AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
PC_LONG val)

AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
PC_DOUBLE val)

AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
PC_LONG val)

AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
PC_CHAR_ARRAY val)

Note: This method sets an array of attribute values, without specifying the number of elements in parameter val.

AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
PC_LONG_ARRAY val,
PC_UINT unSize)

AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
PC_DOUBLE_ARRAY val,
PC_UINT unSize)

AddDiscretionaryAttr(
const PC_SmallString& rkstrName,
PC_BYTE_ARRAY val,
PC_UINT unSize)

rkstrName —: the name of the discretionary attribute whose value is to be set
type —: the data type of the attribute
val —

the value of the specified attribute

unSize —

the number of elements in val

throws —: AddDiscretionaryAttr throws an InvalidNotificationException if rkstrName belongs to a predefined attribute, or, in the case of floating-point types, if val is a NaN.

GetDiscretionaryAttr

void GetDiscretionaryAttr(
const PC_SmallString& rkstrName,
void*& rpVal,
PC_TypeCode& ridTypeCode,
PC_UINT& runSizeIfArray)
throw( InvalidNotificationException)

GetDiscretionaryAttr returns the value of a discretionary attribute of this object. It is the only method for retrieving discretionary attribute values.

GetDiscretionaryAttr is not overloaded by attribute value type because notification recipients are not guaranteed to have a priori awareness of discretionary attribute characteristics.

rkstrName —: the name of the discretionary attribute whose value is to be returned
rpVal —: variable to hold an untyped pointer to the value of the specified attribute, or for array-valued attributes to hold an untyped copy of the array pointer itself
ridTypeCode —: the type code of rpVal
runSizeIfArray —: if idTypeCode designates an array type, then this parameter is the number of elements in the array
throw —: GetDiscretionaryAttr throws an InvalidNotificationException if rkstrName is not the name of a discretionary attribute, or if there is a a problem retrieving the attribute.

DiscretionaryAttrNames

const rgstrNames_t DiscretionaryAttrNames()
throw( InvalidNotificationException)

rgstrNames_t —: the data type of the return
rkstrNames_t —: an array of strings, containing discretionary attribute names
returns —: the names of all discretionary attributes of this object.
throws —: DiscretionaryAttrNames throws an InvalidNotificationException if there is a problem retrieving the discretionary attributes

IsDiscretionaryAttr

bool IsDiscretionaryAttr(const string& rkstrName)

Indicates whether this object has a discretionary attribute of a particular name.

rkstrName —: the discretionary attribute name to check
returns —: true if rkstrName is the name of a discretionary attribute of this object; otherwise, false