pdcomm_gem_result_status_name
Function
Copies one SVID, name, and units entry from an S1F12 result.
PdcommStatus pdcomm_gem_result_status_name(const PdcommGemResult *result, size_t index, uint32_t *out_id, uint8_t *name, size_t name_capacity, size_t *name_required, uint8_t *units, size_t units_capacity, size_t *units_required)Only results with outcome #PDCOMM_GEM_NAMES_RECEIVED support this getter; entry_count gives the number of entries. The SVID comes from the reply; for a request with selected IDs the reply was already checked to match the requested IDs in order. Both required lengths are reported. If either buffer is too small, neither buffer is changed and out_id stays 0. Strings are ASCII bytes with embedded NUL preserved and no added terminator.
Parameters
| Name | Description |
|---|---|
result | Live result. |
index | Zero-based entry index. |
out_id | Receives the SVID on success; set to 0 first. Must not be NULL. |
name | Destination for SVNAME; NULL only with name_capacity 0. |
name_capacity | Size of name in bytes. |
name_required | Receives the name length (set to 0 first when not NULL). Must not be NULL. |
units | Destination for UNITS; NULL only with units_capacity 0. |
units_capacity | Size of units in bytes. |
units_required | Receives the units length (set to 0 first when not NULL). Must not be NULL. |
Returns
#PDCOMM_OK when the entry was copied; #PDCOMM_BUFFER_TOO_SMALL when either capacity is too small (both lengths set, no buffer changed); #PDCOMM_INVALID_ARGUMENT when result, out_id, name_required, or units_required is NULL, or a buffer is NULL with a nonzero capacity; #PDCOMM_INVALID_STATE when the result outcome is not #PDCOMM_GEM_NAMES_RECEIVED; #PDCOMM_OUT_OF_RANGE when index is not less than entry_count; #PDCOMM_INTERNAL_ERROR when a panic was contained.
Notes
- All outputs must be writable, must not overlap each other, and must be separate from the result.
- Thread safety: read-only result getters may run concurrently with each other, but not with pdcomm_gem_result_destroy().