/* * Copyright (C) 2024 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #pragma once #include #include #include #include #include #include #include __BEGIN_DECLS /** * An API to access and operate codecs implemented within an APEX module, * used only by the OS when using the codecs within a client process * (instead of via a HAL). * * NOTE: Many of the constants and types mirror the ones in the Codec 2.0 API. */ /** * Error code for ApexCodec APIs. * * Introduced in API 36. */ typedef enum ApexCodec_Status : int32_t { APEXCODEC_STATUS_OK = 0, /* bad input */ APEXCODEC_STATUS_BAD_VALUE = EINVAL, APEXCODEC_STATUS_BAD_INDEX = ENXIO, APEXCODEC_STATUS_CANNOT_DO = ENOTSUP, /* bad sequencing of events */ APEXCODEC_STATUS_DUPLICATE = EEXIST, APEXCODEC_STATUS_NOT_FOUND = ENOENT, APEXCODEC_STATUS_BAD_STATE = EPERM, APEXCODEC_STATUS_BLOCKING = EWOULDBLOCK, APEXCODEC_STATUS_CANCELED = EINTR, /* bad environment */ APEXCODEC_STATUS_NO_MEMORY = ENOMEM, APEXCODEC_STATUS_REFUSED = EACCES, APEXCODEC_STATUS_TIMED_OUT = ETIMEDOUT, /* bad versioning */ APEXCODEC_STATUS_OMITTED = ENOSYS, /* unknown fatal */ APEXCODEC_STATUS_CORRUPTED = EFAULT, APEXCODEC_STATUS_NO_INIT = ENODEV, } ApexCodec_Status; /** * Enum that represents the kind of component * * Introduced in API 36. */ typedef enum ApexCodec_Kind : uint32_t { /** * The component is of a kind that is not listed below. */ APEXCODEC_KIND_OTHER = 0x0, /** * The component is a decoder, which decodes coded bitstream * into raw buffers. * * Introduced in API 36. */ APEXCODEC_KIND_DECODER = 0x1, /** * The component is an encoder, which encodes raw buffers * into coded bitstream. * * Introduced in API 36. */ APEXCODEC_KIND_ENCODER = 0x2, } ApexCodec_Kind; typedef enum ApexCodec_Domain : uint32_t { /** * A component domain that is not listed below. * * Introduced in API 36. */ APEXCODEC_DOMAIN_OTHER = 0x0, /** * A component domain that operates on video. * * Introduced in API 36. */ APEXCODEC_DOMAIN_VIDEO = 0x1, /** * A component domain that operates on audio. * * Introduced in API 36. */ APEXCODEC_DOMAIN_AUDIO = 0x2, /** * A component domain that operates on image. * * Introduced in API 36. */ APEXCODEC_DOMAIN_IMAGE = 0x3, } ApexCodec_Domain; /** * Handle for component traits such as name, media type, kind (decoder/encoder), * domain (audio/video/image), etc. * * Introduced in API 36. */ typedef struct ApexCodec_ComponentTraits { /** * The name of the component in ASCII encoding. */ const char *_Nonnull name; /** * The supported media type of the component in ASCII encoding. */ const char *_Nonnull mediaType; /** * The kind of the component. */ ApexCodec_Kind kind; /** * The domain on which the component operates. */ ApexCodec_Domain domain; } ApexCodec_ComponentTraits; /** * An opaque struct that represents a component store. * * Introduced in API 36. */ typedef struct ApexCodec_ComponentStore ApexCodec_ComponentStore; /** * Get the component store object. This function never fails. * * \return component store object. */ ApexCodec_ComponentStore *_Nullable ApexCodec_GetComponentStore() __INTRODUCED_IN(36); /** * Get the traits object of a component at given index. ApexCodecs_Traits_* * functions are used to extract information from the traits object. * * Returns nullptr if index is out of bounds. The returned object is owned by * ApexCodec_ComponentStore object and the client should not delete it. * * The client can iterate through the traits objects by calling this function * with an index incrementing from 0 until it gets a nullptr. * * \param index index of the traits object to query * \return traits object at the index, or nullptr if the index is out of bounds. */ ApexCodec_ComponentTraits *_Nullable ApexCodec_Traits_get( ApexCodec_ComponentStore *_Nonnull store, size_t index) __INTRODUCED_IN(36); /** * An opaque struct that represents a codec. */ typedef struct ApexCodec_Component ApexCodec_Component; /** * Create a component by the name. * * \param store the component store * \param name the name of the component in ASCII encoding * \param outComponent out-param to be filled with the component; must not be null * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_NOT_FOUND if the name is not found * \return APEXCODEC_STATUS_CORRUPTED if an unexpected error occurs */ ApexCodec_Status ApexCodec_Component_create( ApexCodec_ComponentStore *_Nonnull store, const char *_Nonnull name, ApexCodec_Component *_Nullable *_Nonnull outComponent) __INTRODUCED_IN(36); /** * Destroy the component by the handle. It is invalid to call component methods on the handle * after calling this method. It is no-op to call this method with |comp| == nullptr. * * \param comp the handle for the component */ void ApexCodec_Component_destroy(ApexCodec_Component *_Nullable comp) __INTRODUCED_IN(36); /** * Start the component. The component is ready to process buffers after this call. * * \param comp the handle for the component * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_STATE if the component is already started or released * \return APEXCODEC_STATUS_CORRUPTED if an unexpected error occurs */ ApexCodec_Status ApexCodec_Component_start( ApexCodec_Component *_Nonnull comp) __INTRODUCED_IN(36); /** * Flush the component's internal states. This operation preserves the existing configurations. * * \param comp the handle for the component * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_STATE if the component is not started * \return APEXCODEC_STATUS_CORRUPTED if an unexpected error occurs */ ApexCodec_Status ApexCodec_Component_flush( ApexCodec_Component *_Nonnull comp) __INTRODUCED_IN(36); /** * Resets the component to the initial state, right after creation. Note that the configuration * will also revert to the initial state, so if there are configurations required those should be * set again to use the component. * * \param comp the handle for the component * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_CORRUPTED if an unexpected error occurs */ ApexCodec_Status ApexCodec_Component_reset( ApexCodec_Component *_Nonnull comp) __INTRODUCED_IN(36); /** * An opaque struct that represents a configurable part of the component. * * Introduced in API 36. */ typedef struct ApexCodec_Configurable ApexCodec_Configurable; /** * Return the configurable object for the given ApexCodec_Component. * The returned object has the same lifecycle as |comp|. * * \param comp the handle for the component * \return the configurable object handle */ ApexCodec_Configurable *_Nonnull ApexCodec_Component_getConfigurable( ApexCodec_Component *_Nonnull comp) __INTRODUCED_IN(36); /** * Enum that represents the flags for ApexCodec_Buffer. * * Introduced in API 36. */ typedef enum ApexCodec_BufferFlags : uint32_t { APEXCODEC_FLAG_DROP_FRAME = (1 << 0), APEXCODEC_FLAG_END_OF_STREAM = (1 << 1), APEXCODEC_FLAG_DISCARD_FRAME = (1 << 2), APEXCODEC_FLAG_INCOMPLETE = (1 << 3), APEXCODEC_FLAG_CORRECTED = (1 << 4), APEXCODEC_FLAG_CORRUPT = (1 << 5), APEXCODEC_FLAG_CODEC_CONFIG = (1u << 31), } ApexCodec_BufferFlags; /** * Enum that represents the type of buffer. * * Introduced in API 36. */ typedef enum ApexCodec_BufferType : uint32_t { APEXCODEC_BUFFER_TYPE_EMPTY, APEXCODEC_BUFFER_TYPE_LINEAR, APEXCODEC_BUFFER_TYPE_LINEAR_CHUNKS, APEXCODEC_BUFFER_TYPE_GRAPHIC, APEXCODEC_BUFFER_TYPE_GRAPHIC_CHUNKS, } ApexCodec_BufferType; /** * Struct that represents the memory for ApexCodec_Buffer. * * All memory regions have the simple 1D representation. * * Introduced in API 36. */ typedef struct ApexCodec_LinearBuffer { /** * A pointer to the start of the buffer. This is not aligned. */ uint8_t *_Nullable data; /** * Size of the buffer. The memory region between |data| (inclusive) and * |data + size| (exclusive) is assumed to be valid for read/write. */ size_t size; } ApexCodec_LinearBuffer; /** * Opaque struct that represents a buffer for ApexCodec_Component. * * The buffer object is used to pass data between the client and the component. * The buffer object is created by ApexCodec_Buffer_create and destroyed by * ApexCodec_Buffer_destroy. The main usage is to pass the buffer to * ApexCodec_Component_process. * * The buffer object is empty by default. The client can set the buffer to be * either linear or graphic by calling ApexCodec_Buffer_setLinearBuffer or * ApexCodec_Buffer_setGraphicBuffer. * * The buffer object can be reused after it is cleared by * ApexCodec_Buffer_clear. The client should set the buffer again before using * it. * * Introduced in API 36. */ typedef struct ApexCodec_Buffer ApexCodec_Buffer; /** * Create an empty buffer object, with no underlying memory or buffer info set. * ApexCodec_Buffer_getType will return APEXCODEC_BUFFER_TYPE_EMPTY, and other getters * will throw APEXCODEC_STATUS_BAD_STATE. * * \return the buffer object handle */ ApexCodec_Buffer *_Nonnull ApexCodec_Buffer_create() __INTRODUCED_IN(36); /** * Destroy the buffer object. No-op if |buffer| is nullptr. Note that ApexCodec_Buffer does not own * objects that are set from the client including linear buffer, graphic buffer, and config updates. * The client therefore is responsible for freeing them if needed. * * The exception is the config updates that are owned by the buffer object, which will be * freed when the buffer object is destroyed. * * \param buffer the buffer object */ void ApexCodec_Buffer_destroy(ApexCodec_Buffer *_Nullable buffer) __INTRODUCED_IN(36); /** * Clear the buffer object to be the empty state; i.e. the same as the buffer object created by * ApexCodec_Buffer_create. * * Similarly to ApexCodec_Buffer_destroy, The client is responsible for freeing objects set to the * buffer if needed. * * \param buffer the buffer object */ void ApexCodec_Buffer_clear(ApexCodec_Buffer *_Nonnull buffer) __INTRODUCED_IN(36); /** * Set the buffer info to the buffer object. * * For input buffers the buffer info is required; otherwise * ApexCodec_Component_process will return APEXCODEC_STATUS_BAD_VALUE. * For output buffers the buffer info is optional. * * When called multiple times, the last set values will be used. * * \param buffer the buffer object * \param flags the flags associated with the buffer * \param frameIndex the frame index for the buffer * \param timestampUs the timestamp for the buffer in microseconds */ void ApexCodec_Buffer_setBufferInfo( ApexCodec_Buffer *_Nonnull buffer, ApexCodec_BufferFlags flags, uint64_t frameIndex, uint64_t timestampUs) __INTRODUCED_IN(36); /** * Set the linear buffer for the empty buffer object. It is an error to call this function if the * buffer is not empty. For example, calling this function twice or after calling * ApexCodec_Buffer_setGraphicBuffer will result in APEXCODEC_STATUS_BAD_STATE, unless the buffer * is cleared first. * * If successful ApexCodec_Buffer_getType will return APEXCODEC_BUFFER_TYPE_LINEAR. * * \param buffer the buffer object * \param linearBuffer the linear buffer to be set; may be null to indicate an empty linear buffer. * an empty linear buffer is used to communicate flags and/or config updates * only to the component. * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_STATE if |buffer| is not empty */ ApexCodec_Status ApexCodec_Buffer_setLinearBuffer( ApexCodec_Buffer *_Nonnull buffer, const ApexCodec_LinearBuffer *_Nullable linearBuffer) __INTRODUCED_IN(36); /** * Set the graphic buffer for the empty buffer object. It is an error to call this function if the * buffer is not empty. For example, calling this function twice or after calling * ApexCodec_Buffer_setLinearBuffer will result in APEXCODEC_STATUS_BAD_STATE, unless the buffer * is cleared first. * * If successful ApexCodec_Buffer_getType will return APEXCODEC_BUFFER_TYPE_GRAPHIC. * * \param buffer the buffer object * \param graphicBuffer the graphic buffer to be set; may be null to indicate * an empty graphic buffer. * an empty graphic buffer is used to communicate flags and/or config updates * only to the component. * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_STATE if |buffer| is not empty */ ApexCodec_Status ApexCodec_Buffer_setGraphicBuffer( ApexCodec_Buffer *_Nonnull buffer, AHardwareBuffer *_Nullable graphicBuffer) __INTRODUCED_IN(36); /** * Set the config updates for the buffer object. * * For input buffers these are sent to the component at the specific input frame. * For output buffers client should not set this; otherwise ApexCodec_Component_process will return * APEXCODEC_STATUS_BAD_VALUE. * * This function cannot be called multiple times on the same buffer object until the buffer object * is cleared. This is to prevent the client from accidentally overwriting the config updates * before the client could free the existing config updates if needed. * * \param buffer the buffer object * \param configUpdates the config updates to be set * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_STATE if config updates are already set */ ApexCodec_Status ApexCodec_Buffer_setConfigUpdates( ApexCodec_Buffer *_Nonnull buffer, const ApexCodec_LinearBuffer *_Nonnull configUpdates) __INTRODUCED_IN(36); /** * Get the type of the buffer object. * * \param buffer the buffer object * \return the type of the buffer object */ ApexCodec_BufferType ApexCodec_Buffer_getType( ApexCodec_Buffer *_Nonnull buffer) __INTRODUCED_IN(36); /** * Extract the buffer info from the buffer object. * * \param buffer the buffer object * \param outFlags the flags associated with the buffer * \param outFrameIndex the frame index for the buffer * for output buffers it is the same as the associated * input buffer's frame index. * \param outTimestampUs the timestamp for the buffer in microseconds * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_STATE if buffer info was never set */ ApexCodec_Status ApexCodec_Buffer_getBufferInfo( ApexCodec_Buffer *_Nonnull buffer, ApexCodec_BufferFlags *_Nonnull outFlags, uint64_t *_Nonnull outFrameIndex, uint64_t *_Nonnull outTimestampUs) __INTRODUCED_IN(36); /** * Extract the linear buffer from the buffer object. * * \param buffer the buffer object * \param outLinearBuffer the linear buffer to be set * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_STATE if |buffer| does not contain a linear buffer */ ApexCodec_Status ApexCodec_Buffer_getLinearBuffer( ApexCodec_Buffer *_Nonnull buffer, ApexCodec_LinearBuffer *_Nonnull outLinearBuffer) __INTRODUCED_IN(36); /** * Extract the graphic buffer from the buffer object. * * \param buffer the buffer object * \param outGraphicBuffer the graphic buffer to be set * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_STATE if |buffer| does not contain a graphic buffer */ ApexCodec_Status ApexCodec_Buffer_getGraphicBuffer( ApexCodec_Buffer *_Nonnull buffer, AHardwareBuffer *_Nullable *_Nonnull outGraphicBuffer) __INTRODUCED_IN(36); /** * Extract the config updates from the buffer object. * For output buffers these are config updates as a result of processing the buffer. * * \param buffer the buffer object * \param outConfigUpdates the config updates to be set. * if the config update was set by the client via * ApexCodec_Buffer_setConfigUpdates, the config updates are the same as * what was set before. |outOwnedByClient| will be set to true. * if the config update was set by the component, |outOwnedByClient| will * be set to false. * \param outOwnedByClient if true, the client owns the config updates and is responsible * for freeing it. * if false, the config updates are owned by the buffer object * and the client should not free it; it will be freed when the buffer * object is cleared or destroyed. * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_NOT_FOUND if |buffer| does not contain config updates */ ApexCodec_Status ApexCodec_Buffer_getConfigUpdates( ApexCodec_Buffer *_Nonnull buffer, ApexCodec_LinearBuffer *_Nonnull outConfigUpdates, bool *_Nonnull outOwnedByClient) __INTRODUCED_IN(36); /** * An opaque struct that represents the supported values of a parameter. * * Introduced in API 36. */ typedef struct ApexCodec_SupportedValues ApexCodec_SupportedValues; /** * Extract information from ApexCodec_SupportedValues object. * * \param supportedValues the supported values object * \param outType pointer to be filled with the type of the supported values * \param outNumberType pointer to be filled with the numeric type of the supported values * \param outValues pointer to be filled with the array of the actual supported values. * if type == APEXCODEC_SUPPORTED_VALUES_EMPTY: nullptr * if type == APEXCODEC_SUPPORTED_VALUES_RANGE: {min, max, step, num, den} * if type == APEXCODEC_SUPPORTED_VALUES_VALUES/_FLAGS: * the array of supported values/flags * the array is owned by the |supportedValues| object and the client * should not free it. * \param outNumValues pointer to be filled with the number of values. * if type == APEXCODEC_SUPPORTED_VALUES_EMPTY: 0 * if type == APEXCODEC_SUPPORTED_VALUES_RANGE: 5 * if type == APEXCODEC_SUPPORTED_VALUES_VALUES/_FLAGS: varies * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_VALUE if the parameters are bad * \return APEXCODEC_STATUS_CORRUPTED if an unexpected error occurs */ ApexCodec_Status ApexCodec_SupportedValues_getTypeAndValues( ApexCodec_SupportedValues *_Nonnull supportedValues, ApexCodec_SupportedValuesType *_Nonnull outType, ApexCodec_SupportedValuesNumberType *_Nonnull outNumberType, ApexCodec_Value *_Nullable *_Nonnull outValues, uint32_t *_Nonnull outNumValues) __INTRODUCED_IN(36); /** * Destroy the supported values object. No-op if |values| is nullptr. * * \param values the supported values object */ void ApexCodec_SupportedValues_destroy( ApexCodec_SupportedValues *_Nullable values) __INTRODUCED_IN(36); /** * Struct that represents the result of ApexCodec_Configurable_config. * * Introduced in API 36. */ typedef struct ApexCodec_SettingResults ApexCodec_SettingResults; /** * Extract the result of ApexCodec_Configurable_config. * The client can iterate through the results with index starting from 0 until this function returns * APEXCODEC_STATUS_NOT_FOUND. * * \param result the result object * \param index the index of the result to extract, starts from 0. * \param outFailure pointer to be filled with the failure code * \param outField pointer to be filled with the field that failed. * |field->value| is owned by the |result| object and the client should not * free it. * \param outConflicts pointer to be filled with the array of conflicts. * nullptr if |numConflicts| is 0. * the array and its content is owned by the |result| object and the client * should not free it. * \param outNumConflicts pointer to be filled with the number of conflicts * may be 0 if there are no conflicts * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_NOT_FOUND if index is out of range * \return APEXCODEC_STATUS_BAD_VALUE if the parameters are bad */ ApexCodec_Status ApexCodec_SettingResults_getResultAtIndex( ApexCodec_SettingResults *_Nonnull results, size_t index, ApexCodec_SettingResultFailure *_Nonnull outFailure, ApexCodec_ParamFieldValues *_Nonnull outField, ApexCodec_ParamFieldValues *_Nullable *_Nonnull outConflicts, size_t *_Nonnull outNumConflicts) __INTRODUCED_IN(36); /** * Destroy the setting result object. No-op if |results| is nullptr. * * \param result the setting result object */ void ApexCodec_SettingResults_destroy( ApexCodec_SettingResults *_Nullable results) __INTRODUCED_IN(36); /** * Process one frame from |input|, and produce one frame to |output| if possible. * * When successfully filled, |outProduced| has the size adjusted to the produced * output size, in case of linear buffers. |input->configUpdates| is applied with the input * buffer; |output->configUpdates| contains config updates as a result of processing the frame. * * \param comp the component to process the buffers * \param input the input buffer; when nullptr, the component should fill |output| * if there are any pending output buffers. * \param output the output buffer, should not be nullptr. * \param outConsumed the number of consumed bytes from the input buffer * set to 0 if no input buffer has been consumed, including |input| is nullptr. * for graphic buffers, any non-zero value means that * the input buffer is consumed. * \param outProduced the number of bytes produced on the output buffer * set to 0 if no output buffer has been produced. * for graphic buffers, any non-zero value means that * the output buffer is filled. * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_NO_MEMORY if the output buffer is not suitable to hold the output frame * the client should retry with a new output buffer; * configUpdates should have the information to update * the buffer size. * \return APEXCODEC_STATUS_BAD_VALUE if the parameters are bad * \return APEXCODEC_STATUS_BAD_STATE if the component is not in the right state * to process the frame * \return APEXCODEC_STATUS_CORRUPTED if unexpected error has occurred */ ApexCodec_Status ApexCodec_Component_process( ApexCodec_Component *_Nonnull comp, const ApexCodec_Buffer *_Nullable input, ApexCodec_Buffer *_Nonnull output, size_t *_Nonnull outConsumed, size_t *_Nonnull outProduced) __INTRODUCED_IN(36); /** * Configure the component with the given config. * * Configurations are Codec 2.0 configs in binary blobs, * concatenated if there are multiple configs. * * frameworks/av/media/codec2/core/include/C2Param.h contains more details about the configuration * blob layout. * * The component may correct the configured parameters to the closest supported values, and could * fail in case there are no values that the component can auto-correct to. |result| contains the * information about the failures. See ApexCodec_SettingResultFailure and ApexCodec_SettingResults * for more details. * * \param comp the handle for the component * \param inoutConfig the config blob; after the call, the config blob is updated to the actual * config by the component. * \param outResult the result of the configuration. * the client should call ApexCodec_SettingResult_getResultAtIndex() * to extract the result. The result object is owned by the client and should * be released with ApexCodec_SettingResult_destroy(). * |result| may be nullptr if empty. * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_VALUE if the config is invalid * \return APEXCODEC_STATUS_BAD_STATE if the component is not in the right state to be configured * \return APEXCODEC_STATUS_CORRUPTED if unexpected error has occurred */ ApexCodec_Status ApexCodec_Configurable_config( ApexCodec_Configurable *_Nonnull comp, ApexCodec_LinearBuffer *_Nonnull inoutConfig, ApexCodec_SettingResults *_Nullable *_Nonnull outResults) __INTRODUCED_IN(36); /** * Query the component for the given indices. * * Parameter indices are defined in frameworks/av/media/codec2/core/include/C2Config.h. * * \param comp the handle for the component * \param indices the array of indices to query * \param numIndices the size of the indices array * \param inoutConfig the output buffer for the config blob, allocated by the client. * it can be null to query the required size. * \param outWrittenOrRequired the number of bytes written to |config|. * if the |config->size| was insufficient, it is set to the * required size. * * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_NO_MEMORY if |config.size| is too small; |config.size| is updated * to the requested buffer size. * \return APEXCODEC_STATUS_BAD_VALUE if the parameters are bad. e.g. |indices| or * |written| is nullptr. */ ApexCodec_Status ApexCodec_Configurable_query( ApexCodec_Configurable *_Nonnull comp, uint32_t indices[_Nonnull], size_t numIndices, ApexCodec_LinearBuffer *_Nullable inoutConfig, size_t *_Nonnull outWrittenOrRequired) __INTRODUCED_IN(36); /** * Struct that represents a parameter descriptor. * * Introduced in API 36. */ typedef struct ApexCodec_ParamDescriptors ApexCodec_ParamDescriptors; /** * Get the parameter indices of the param descriptors. * * \param descriptors the param descriptors object * \param outIndices the pointer to be filled with the array of the indices; * the array is owned by |descriptors| and should not be freed by the client. * \param outNumIndices the size of the indices array * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_VALUE if parameters are bad. e.g. |descriptors|, |indices| or * |numIndices| is nullptr. */ ApexCodec_Status ApexCodec_ParamDescriptors_getIndices( ApexCodec_ParamDescriptors *_Nonnull descriptors, uint32_t *_Nullable *_Nonnull outIndices, size_t *_Nonnull outNumIndices) __INTRODUCED_IN(36); /** * Get the descriptor of the param. * * \param descriptors the param descriptors object * \param index the index of the param * \param outAttr the attribute of the param * \param outName the pointer to be filled with the name of the param * the string is owned by |descriptors| and should not be freed by the client. * the encoding is ASCII. * \param outDependencies the pointer to be filled with an array of the parameter indices * that the parameter with |index| depends on. * may be null if empty. * the array is owned by |descriptors| and should not be freed by the client. * \param outNumDependencies the number of dependencies * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_VALUE if parameters are bad. e.g. |descriptors|, |attr|, |name|, * |dependencies| or |numDependencies| is nullptr. * \return APEXCODEC_STATUS_BAD_INDEX if the index is not included in the param descriptors. */ ApexCodec_Status ApexCodec_ParamDescriptors_getDescriptor( ApexCodec_ParamDescriptors *_Nonnull descriptors, uint32_t index, ApexCodec_ParamAttribute *_Nonnull outAttr, const char *_Nullable *_Nonnull outName, uint32_t *_Nullable *_Nonnull outDependencies, size_t *_Nonnull outNumDependencies) __INTRODUCED_IN(36); /** * Destroy the param descriptors object. No-op if |descriptors| is nullptr. * * \param descriptors the param descriptors object */ void ApexCodec_ParamDescriptors_destroy( ApexCodec_ParamDescriptors *_Nullable descriptors) __INTRODUCED_IN(36); /** * Query the component for the supported parameters. * * \param comp the handle for the component * \param outDescriptors the pointer to be filled with the param descriptors object * the object should be released with ApexCodec_ParamDescriptors_destroy(). * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_BAD_VALUE if parameters are bad. e.g. |descriptors| is nullptr. */ ApexCodec_Status ApexCodec_Configurable_querySupportedParams( ApexCodec_Configurable *_Nonnull comp, ApexCodec_ParamDescriptors *_Nullable *_Nonnull outDescriptors) __INTRODUCED_IN(36); /** * Struct that represents the query for the supported values of a parameter. * * The offset of the field can be found in the layout of the parameter blob. * * Introduced in API 36. */ typedef struct ApexCodec_SupportedValuesQuery { /* in-params */ /** index of the param */ uint32_t index; /** offset to the param field */ size_t offset; /** query type */ ApexCodec_SupportedValuesQueryType type; /* out-params */ /** status of the query */ ApexCodec_Status status; /** supported values. must be released with ApexCodec_SupportedValues_destroy(). */ ApexCodec_SupportedValues *_Nullable values; } ApexCodec_SupportedValuesQuery; /** * Query the component for the supported values of the given indices. * * \param comp the handle for the component * \param inoutQueries the array of queries * \param numQueries the size of the queries array * \return APEXCODEC_STATUS_OK if successful * \return APEXCODEC_STATUS_CORRUPTED if unexpected error has occurred */ ApexCodec_Status ApexCodec_Configurable_querySupportedValues( ApexCodec_Configurable *_Nonnull comp, ApexCodec_SupportedValuesQuery *_Nonnull inoutQueries, size_t numQueries) __INTRODUCED_IN(36); __END_DECLS