pdcomm_gem_equipment_alarm_at
Function
Reads one stored alarm by registration index and copies its text.
PdcommStatus pdcomm_gem_equipment_alarm_at(PdcommTcpEndpoint *endpoint, size_t index, PdcommGemAlarmInfo *info, uint8_t *text, size_t capacity, size_t *required)Index 0 is the first definition passed to pdcomm_gem_equipment_configure_alarms(). Before any lookup, the known fields of info are cleared and *required is set to 0, so a bad index leaves them cleared. When capacity is too short, info and *required are still written and text is untouched.
Parameters
| Name | Description |
|---|---|
endpoint | Endpoint with a configured GEM Equipment and alarm store. |
index | Zero-based registration index. |
info | Caller storage; set info->struct_size before the call. |
text | Destination for the alarm text. May be NULL only when capacity is 0. |
capacity | Size of text in bytes. |
required | Receives the alarm text length. Must not be NULL. |
Returns
#PDCOMM_OK when the alarm and its text were copied; #PDCOMM_BUFFER_TOO_SMALL when capacity is smaller than the text (metadata written, text untouched); #PDCOMM_INVALID_ARGUMENT when endpoint, info, or required is NULL, text is NULL with a nonzero capacity, the outputs overlap, or info->struct_size is too small; #PDCOMM_OUT_OF_RANGE when index is not less than the alarm count; #PDCOMM_INVALID_STATE when the endpoint has no GEM Equipment or no alarm store; #PDCOMM_POISONED when the endpoint is poisoned or a panic was contained.
Notes
info,text, andrequiredmust not overlap each other; the library rejects overlapping ranges.