Qeo Open Source Project Documentation : C

Using The API

During the creation of a Qeo reader or writer you can optionally specify an on policy update callback method.  If the callback is specified then Qeo will call it:

1. When creating the reader or writer,
2. Whenever a Qeo Policy update is received,
3. When requesting a Qeo Policy re-evaluation (see below).

When the callback method gets called:

1. It will receive a Qeo Policy identity.
2. It should decide whether it will allow or deny the provided identity from being read from or written to.

The callback will be called:

1. Once for each user (identity) to whom you're allowed to communicate in your realm. This is defined by the policy of the realm.
2. Once with a null identity to signal that the end of the Qeo Policy was reached. 

In some cases an application may want to reconsider a decision made earlier on whom to allow or deny for a certain reader or writer.  For this reason each entity also has a policy update method that allows the application to request a re-evaluation of the Qeo Policy.  When calling this method the on policy update callback will be called again for each relevant identity in the Qeo Policy.

The on_policy_update Callback

The following arguments are passed to the callback:

• The reader or writer on which the callback is triggered,
• A Qeo Policy identity,
• The user data that was provided during reader or writer creation.

The callback should return one off:

• QEO_POLICY_ALLOW to allow the provided identity from being read from or written to.
• QEO_POLICY_DENY to deny the provided identity from being read from or written to.

//callback for a qeo_event_writer_t.
static qeo_policy_perm_t on_policy_update(const qeo_event_writer_t *writer,
                                          const qeo_policy_identity_t *identity,
                                          uintptr_t userdata)
{
    return QEO_POLICY_ALLOW;
}

Registration of the listener during reader/writer creation

//listener structure
static qeo_event_writer_listener_t _wl = { on_policy_update };

//registering the listener structure
msg_writer = qeo_factory_create_event_writer(qeo, my_qeo_type, &_wl, 0);

Note: the reader/writer creation will block untill all the on_policy_update callbacks for that reader/writer are handled. This ensures the reader/writer can only be used after the correct policies are set.

Forcing a policy update

If you want to change a policy, you need to request an update in order for the on_policy_update callback to be called again

//trigger an update for an event writer
qeo_event_writer_policy_update(writer);

Note: this call will block until all the on_policy_update callbacks are handled.