Notification

PreCache NetInjector Documentation Center : PreCache NetInjector API Reference

C Types and Functions

C Types and Functions

Subscription handlers

PC_evn_Channel_Info

Notification

— the data for an event to be published

A Notification stores information about a single event that is to be published over a channel.

The object stores a subject for the notification as well as values for attributes that provide additional information about the event.

Type

typedef void* PC_evn_Notification

Functions

PC_evn_create_notification

PC_Status PC_EXPORT PC_evn_create_notification(
PC_evn_Notification* pNotification,
PC_evn_Proxy proxy,
PC_CHAR* szSubject,
PC_CHAR* szAttrVals)

Creates a notification object from a subject string and an optional list of attribute assignments, and associates the notification with a proxy.

pNotification —: a pointer to a variable to hold the newly-allocated notification
proxy —: 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
szSubject —: a subject for the notification
szAttrVals —: PC_NULL, or a comma-separated sequence of attribute assignments of the form name=(type)value
returns —: PC_INVALID_SUBJECT, if the specified subject is invalid for the underlying channel (in which case pNotification is set to PC_NULL); PC_INVALID_NOTIFICATION, if there is a problem setting up the notification message or if attribute assignments (the value of szAttrVals) have been supplied; otherwise PC_SUCCESS.

PC_evn_copy_notification

PC_Status PC_EXPORT PC_evn_copy_notification(
PC_evn_Notification* pNotificationNew,
PC_evn_Notification notificationOld)

Creates a copy of a notification.

pNotificationNew —: a pointer to a variable to hold the newly-allocated copy
notificationOld —: the notification to be copied
returns —: PC_INVALID_NOTIFICATION, if the attempt to copy was unsuccessful (in which case pNotificationNew is set to PC_NULL); otherwise PC_SUCCESS

PC_evn_destroy_notification

PC_Status PC_EXPORT PC_evn_destroy_notification(
PC_evn_Notification notification)

Releases the resources associated with a notification.

notification —: the notification to be destroyed; the argument passed for notification is no longer valid upon return from the function
returns —: PC_SUCCESS

PC_evn_get_subject

PC_Status PC_EXPORT PC_evn_get_subject(
PC_evn_Notification notification,
PC_CHAR** pszSubject)

Returns the subject of a notification.

notification —: the notification whose subject is to be returned
pszSubject —: a pointer to a variable to hold the newly-allocated subject string; should be destroyed with PC_evn_destroy_subject
returns —: PC_SUCCESS

PC_evn_destroy_subject

PC_Status PC_EXPORT PC_evn_destroy_subject(
PC_CHAR* szSubject)

Destroys the buffer allocated in a previous call to PC_evn_get_subject.

szSubject —: the subject buffer to be destroyed
returns —: PC_SUCCESS

PC_evn_get_subject_mapping

PC_Status PC_evn_get_subject_mapping(
PC_evn_Notification notification,
PC_UINT16** prgunSubjectFields,
PC_UINT* pcSubjectFields)

Returns the mapping of a notification's subject to its array of subject field

notification —: the notification whose subject mapping is to be returned
prgunSubjectFields —: a pointer to a variable to hold the array of subject field mappings; should be destroyed with PC_evn_destroy_subject_mapping
pcSubjectFields —: a pointer to a variable to hold the number of fields in the returned array
returns —: PC_SUCCESS

PC_evn_destroy_subject_mapping

PC_Status PC_EXPORT PC_evn_destroy_subject_mapping(
PC_UINT16* rgunSubjectFields)

Destroys the buffer allocated in a previous call to PC_evn_get_subject_mapping.

rgunSubjectFields —: the buffer to be destroyed
returns —: PC_SUCCESS

PC_evn_set_predefined_attr_by_pos

PC_Status PC_EXPORT PC_evn_set_predefined_attr_by_pos(
PC_evn_Notification notification,
PC_UINT unPos,void* pVal,
PC_TypeCode idTypeCode,
PC_UINT unSize)

Sets the value of a predefined attribute of a notification, identified by its position.

notification —: the notification whose attribute is to be set
unPos —: the position of the predefined attribute whose value is to be set
pVal —: a pointer to the value to be assigned to the attribute (which itself may be a pointer in the case of an array or string value); the caller must ensure that the value is of the correct type
idTypeCode —: the typecode of pVal
unSize —: for array-valued attributes, the size of the array
returns —: PC_INVALID_NOTIFICATION, if there is no predefined attribute in the specified position, or if idTypeCode is not the same as the type of the attribute as determined by the notification type of the channel; otherwise PC_SUCCESS

PC_evn_set_predefined_attr_by_name

PC_Status PC_EXPORT PC_evn_set_predefined_attr_by_name( PC_evn_Notification notification,
PC_CHAR* szName,void* pVal,
PC_TypeCode idTypeCode,
PC_UINT unSize)

Sets the value of a predefined attribute of a notification, identified by its name.

notification —: the notification whose attribute is to be set
szName —: the name of the predefined attribute whose value is to be set
pVal —: a pointer to the value to be assigned to the attribute (which itself may be a pointer in the case of an array or string value); the caller must ensure that the value is of the correct type
idTypeCode —: the typecode of pVal
unSize —: for array-valued attributes, the size of the array
returns —: PC_INVALID_NOTIFICATION, if szName is not the name of a predefined attribute, or if idTypeCode is not the same as the type of the attribute as determined by the notification type of the channel; otherwise PC_SUCCESS

PC_evn_get_predefined_attr_by_pos

PC_Status PC_EXPORT PC_evn_get_predefined_attr_by_pos(
PC_evn_Notification notification,
PC_UINT unPos,void** ppVal,
PC_TypeCode idTypeCode,
PC_UINT* punSize)

Returns the value of a predefined attribute of a notification, identified by its position.

notification —: the notification whose attribute is to be returned
unPos —: the position of the predefined attribute whose value is to be returned
ppVal —: a pointer to a 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 typecode of pVal
punSize —: for array-valued attributes, a pointer to a variable to hold the size of the array
returns —: PC_INVALID_NOTIFICATION, if there is no predefined attribute in the specified position, or if idTypeCode is not the same as the type of the attribute as determined by the notification type of the channel; otherwise PC_SUCCESS

PC_evn_get_predefined_attr_by_name

PC_Status PC_EXPORT PC_evn_get_predefined_attr_by_name(
PC_evn_Notification notification,
PC_CHAR* szName,void** ppVal,
PC_TypeCode idTypeCode,
PC_UINT* punSize)

Returns the value of a predefined attribute of a notification, identified by its name.

notification —: the notification whose attribute is to be returned
szName —: the name of the predefined attribute whose value is to be returned
ppVal —: a pointer to a 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 typecode of pVal
punSize —: for array-valued attributes, a pointer to a variable to hold the size of the array
returns —: PC_INVALID_NOTIFICATION, if szName is not the name of a predefined attribute, or if idTypeCode is not the same as the type of the attribute as determined by the notification type of the underlying channel; otherwise PC_SUCCESS

PC_evn_add_discretionary_attr

PC_Status PC_EXPORT PC_evn_add_discretionary_attr(
PC_evn_Notification notification,
PC_CHAR* szName,void* pVal,
PC_TypeCode idTypeCode,
PC_UINT unSize)

Sets the value of a discretionary attribute of a notification.

notification —: the notification whose attribute is to be set
szName —: the name of the discretionary attribute whose value is to be set
pVal —: a pointer to the value to be assigned to the attribute (which itself may be a pointer in the case of an array or string value); the caller must ensure that the value is of the correct type
idTypeCode —: the typecode of pVal
unSize —: for array-valued attributes, the size of the array
returns —: PC_INVALID_NOTIFICATION, if szName is the name of a predefined attribute; otherwise PC_SUCCESS

PC_evn_get_discretionary_attr_names

PC_Status PC_EXPORT PC_evn_get_discretionary_attr_names(
PC_evn_Notification notification,
PC_CHAR*** prgszNames,
PC_UINT* punSize)

Returns the names of all discretionary attributes of this object.

notification —: the notification whose discretionary attribute names are to be returned
prgszNames —: a pointer to a variable to hold the newly-allocated array of names; should be destroyed with PC_evn_destroy_discretionary_attr_names
punSize —: a pointer to a variable to hold the number of elements in prgszNames
returns —: PC_INVALID_NOTIFICATION, if there is a problem retrieving the discretionary attributes; otherwise PC_SUCCESS

PC_evn_is_discretionary_attr

PC_BOOL PC_EXPORT PC_evn_is_discretionary_attr(
PC_evn_Notification notification,
PC_CHAR* szName)

Returns an indication of whether or not this object has a discretionary attribute of a particular name.

notification —: the notification whose discretionary attributes are to be checked
szName —: the discretionary attribute name to check
returns —: true, if szName is the name of a discretionary attribute of notification; otherwise false

PC_evn_destroy_discretionary_attr_names

PC_Status PC_EXPORT PC_evn_destroy_discretionary_attr_names(
PC_CHAR** rgszNames,
PC_UINT unSize)

Destroys the buffer allocated in a previous call to PC_evn_get_discretionary_attr_names.

rgszNames —: the buffer to be destroyed
unSize —: the number of elements in rgszNames
returns —: PC_SUCCESS

PC_evn_get_discretionary_attr

PC_Status PC_EXPORT PC_evn_get_discretionary_attr(
PC_evn_Notification notification,
PC_CHAR* szName,void** ppVal,
PC_TypeCode* pidTypeCode,
PC_UINT* punSize)

Returns the value of a discretionary attribute of a notification.

notification —: the notification whose attribute is to be returned
szName —: the name of the discretionary attribute whose value is to be returned
ppVal —: a pointer to a 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
pidTypeCode —: a pointer to a variable to hold the typecode of ppVal
punSize —: for array-valued attributes, a pointer to a variable to hold the size of the array
returns —: PC_INVALID_NOTIFICATION, if szName is the name of a discretionary attribute; otherwise PC_SUCCESS