Description

The bc parameter should be a bundle descriptor reference as returned by a suitable cyg_bundle_access_…() call.

After obtaining a context for the chosen “access” strategy this function must be called to verify that the bundle is valid prior to any subsequent data access API calls, since this function also initialises context data-structures required by the item access API functions.

Currently the valid_signature_mask and valid_signature parameters are not used. The code may be extended in the future to allow bundle validity to be selected based on the 8-bits of platform/application ID specific signature.

The following pseudo code is an example of expected, normal, use case of this function after selecting an access method:

#include <pkgconf/system.h>
#include <pkgconf/bundle.h>

#include <cyg/bundle/bundle.h>
#include <cyg/bundle/bundle_api.h>

void do_some_work(int fd)
{
    cyg_bundle_context_t *bc;

    bc = cyg_bundle_access_file(fd);
    if (bc) {
        if (CYG_BUNDLE_VALID == cyg_bundle_verify(bc,CYG_BUNDLE_SIG_MASK,CYG_BUNDLE_SIG_BASE)) {

            … perform item, or bundle arbitrary data, operations …

        } else {
            …report bundle validity error…
        }

        cyg_bundle_access_release(bc);
    } else {
        …report file access error…
    }

    return;
}

Return value

If the bundle is valid then the value CYG_BUNDLE_VALID is returned, and the bc context will be valid for subsequent item API calls. If the bundle data is invalid, or cannot be read, then CYG_BUNDLE_INVALID is returned.