pdcomm_gem300_capability_catalog_replace
Function
Atomically replaces the catalog contents with an ordered list of profiles.
PdcommStatus pdcomm_gem300_capability_catalog_replace(PdcommGem300CapabilityCatalog *catalog, const PdcommGem300CapabilityProfile *profiles, size_t profile_count, uint64_t *out_revision, uint8_t *out_changed)The complete input is validated against the catalog limits and copied before the catalog changes, so the caller's arrays may be released when the call returns. On any error the catalog keeps its previous contents and revision. When the input equals the current contents in order and value, the call succeeds with *out_changed 0 and the revision unchanged; otherwise the revision is incremented. NULL profiles with profile_count 0 clears the catalog through the same contract.
Parameters
| Name | Description |
|---|---|
catalog | Catalog to change. |
profiles | Array of profile_count profiles. May be NULL when profile_count is 0. |
profile_count | Number of profiles; at most max_profiles. |
out_revision | Receives the revision after the call. Must not be NULL; set to 0 before validation. |
out_changed | Receives 1 when the contents changed, otherwise 0. Must not be NULL; set to 0 before validation. |
Returns
#PDCOMM_OK on success; #PDCOMM_INVALID_ARGUMENT when an output or catalog is NULL, a pointer is NULL with a nonzero count or length, a reserved field is nonzero, an axis, status, or verification value is unknown, a profile has no capabilities, an identifier is empty or contains a byte outside 0x21 to 0x7E, or a profile identifier, a capability identifier within its profile, or an axis within its profile is repeated; #PDCOMM_LIMIT_EXCEEDED when a catalog limit is exceeded or the revision counter is exhausted; #PDCOMM_LICENSE_REQUIRED when no license grants the gem300 module (checked after the pointer arguments and before the profiles are validated; the catalog is unchanged); #PDCOMM_ALLOCATION_FAILED or #PDCOMM_INTERNAL_ERROR.
Notes
- Thread safety: serialize with every other call on the same catalog.