[Open-scap] RE: Probe context API

[David Niemoller]

Thanx, Daniel, I will be taking a close look at your API.  I like your
provision of a reset function.  I've recently started considering the
same sort of functionality for the public Syschar APIs.

-----Original Message-----
From: Daniel Kopecek [mailto:dkopecek at redhat.com] 
Sent: Wednesday, November 18, 2009 5:42 AM
To: OpenSCAP list
Cc: David Niemoller
Subject: Probe context API

Hello,
 I have recently pushed the first bits of probe context API into our
repository. Two API functions were changed and several new functions
were added.

First the name changes:

 oval_object_probe -> oval_probe_object_eval  oval_sysinf_probe ->
oval_probe_sysing_eval

And here is the list of new functions with short descriptions:

oval_pctx_t *oval_pctx_new(struct oval_definition_model *model);
void         oval_pctx_free(oval_pctx_t *ctx);

Functions for creating and destroying probe context. The first argument
of oval_pctx_new() is a pointer to the definition model.
oval_probe_object_eval no longer accepts this pointer because it takes
it from the probe context instead. It is possible to change the pointer
by calling oval_pctx_setattr(OVAL_PCTX_ATTR_MODEL, new_pointer).

 int oval_pctx_setflag(oval_pctx_t *ctx, uint32_t flags);  int
oval_pctx_unsetflag(oval_pctx_t *ctx, uint32_t flags);  int
oval_pctx_setattr(oval_pctx_t *ctx, uint32_t attr, ...);

These functions are mainly for modifying the behavior of the underlying
communication protocol (timeouts, retry count, etc). Possible flags and
attributes are listed in the public header oval_probe.h and they will be
later available in the documentation.

 int oval_probe_reset(oval_pctx_t *, oval_subtype_t);

Function for reseting the state (cache, counters, etc) associated with a
probe of specified subtype. A special subtype OVAL_SUBTYPE_ALL can be
used to apply this operation on all probes.

 int oval_probe_close(oval_pctx_t *, oval_subtype_t);

Function for closing the connection to a probe (this also clears the
cache since it is located in the probe) and terminating the probe's
process. OVAL_SUBTYPE_ALL works the same way as for the previous
function.

struct oval_sysinfo *oval_probe_sysinf_eval(oval_pctx_t *); struct
oval_syschar *oval_probe_object_eval(oval_pctx_t *, struct oval_object
*);

These are the new versions of oval_object_probe and oval_sysinf_probe.
Both take the context pointer as their first argument.

The working implementation of this interface will be available later
this week (reset, close, flags and attributes aren't implemented yet)
I'm sending the description beforehand because I made some changes in
the OVAL code.
I've moved the declaration of oval_probe_{sysinf,object}_eval into the
new public header which is located in src/OVAL/public/oval_probe.h. This
file is included from oval_agent_api.h to preserve the availability of
the "probe calling" functions. However, this doesn't work since the
definition model type (struct oval_definition_model) is declared in
oval_agent_api.h and not in oval_definitions.h. I've moved the
declaration to oval_definitions.h. Please let me know (David) if this is
wrong and whether it should be declared in oval_agent_api.h for some
reason. Also, I've added a new subtype to oval_subtype_t enum -
OVAL_SUBTYPE_ALL (the purpose is described above).

Dan