OMadd_notify_req and OMdel_notify_req
Synopsis
void OMadd_notify_req (
OMobj_id object_id,
OMobj_id template_id,
OMobj_id method_id,
OMobj_id argument_id,
unsigned int event_mask,
int mode );
void OMdel_notify_req (
OMobj_id object_id,
OMobj_id template_id,
OMobj_id method_id,
OMobj_id argument_id,
unsigned int event_mask,
int mode );
Description
These routines add or delete a notification request. These routines are used by method objects to implement their callback functionality. You do not typically need to call them yourself.
Arguments
object_id
The id of the object on which to place the notification request. That is, a notification request is to be generated when an event occurs in object_id .
template_id
The optional id of a template of subobjects on which to place the notification. See Example 2 below.
To indicate no object, specify OMnull_obj.
method_id
The id of the method object to be notified when the event occurs.
argument_id
An optional object id to be passed to the invoked function.
To indicate no id, specify OMnull_obj.
event_mask
The events that, when they occur in object_id , will cause a notification on the function.
The events are as follows:
|
Event name
|
Event
|
Properties
|
|
OM_EVENT_VAL |
Value changed |
Propagated
|
|
OM_EVENT_ADD_SUBOBJ |
Subobject added |
Not propagated
|
|
OM_EVENT_DEL_SUBOBJ |
Subobject deleted |
Not propagated
|
|
OM_EVENT_INST |
Object instanced |
Not propagated
|
|
OM_EVENT_ATT |
Attribute changed |
Not propagated
|
|
OM_EVENT_DEL |
Object about to be deleted |
Not propagated
|
|
OM_EVENT_PROP |
Property changed |
Not propagated
|
Notes:
1. a. Propagated means that the notification request extends to objects referenced in the object_id 's value parameter, and to objects referenced by those objects, and so forth.
Queued means that if the notification is generated, it is added to AVS/Express' internal queue of notifications to process. Not queued means that AVS/Express processes the notifications immediately.
mode
Options when adding notifications. mode is ignored in a call to OMdel_notify_req.
mode can be any of the following. You can OR together individual modes.
|
Mode
|
Meaning
|
|
0 |
No options apply. |
|
OM_NOTIFY_NOSUBOBJS |
The notification is generated only if an event occurs on object_id itself. By default, a notification is generated if the event occurs on either object_id or any of its subobjects. |
|
OM_NOTIFY_IMM |
If the notification is generated, it is processed immediately, even if its property is queued on the events specified. |
Example 1
/* Notify myfunc_id when val1_id's property has changed.
Pass myfunc_id as an argument. */
OMobj_id myfunc_id, val1_id,my_arg;
...
OMadd_notify_req(val1_id, OMnull_obj, myfunc_id, my_arg,
OM_EVENT_PROP, 0);
Example 2
Here is an example of using template_id .
The V code below defines group g3 as follows:
group g1 {
int a;
int b;
};
group g2 {
int c;
};
g1+g2 g3 {
int d;
};
If you put a notification request on g3, by default a notification will be generated if any of g3's subobjects change, including subobjects a, b, c, and d.
To limit the notification to g3 and the subobjects inherited from g1, you can do the following:
OMobj_id myfunc_id, g3_id, g1_id, my_arg;
...
OMadd_notify_req(g3_id, g1_id, myfunc_id, may_arg,
OM_EVENT_VAL, 0);