Quantum Resource Management Interface (QRMI) C API
Loading...
Searching...
No Matches
qrmi.h File Reference

Go to the source code of this file.

Classes

struct  QrmiKeyValue
struct  QrmiEnvironmentVariables
struct  QrmiResourceDef
struct  QrmiResourceCapacity
struct  QrmiPayload_QiskitPrimitive_Body
struct  QrmiPayload_PasqalCloud_Body
struct  QrmiPayload_AliceBobFelis_Body
struct  QrmiPayload_IQMServer_Body
struct  QrmiPayload_Oqtopus_Body
struct  QrmiPayload_MaestroLocal_Body
struct  QrmiPayload
struct  QrmiQuantumResources

Typedefs

typedef struct QrmiConfig QrmiConfig
typedef struct QrmiQuantumResource QrmiQuantumResource
typedef struct QrmiResourceMetadata QrmiResourceMetadata
typedef struct QrmiResourceProvider QrmiResourceProvider
typedef struct QrmiResourceStatus QrmiResourceStatus
typedef void(* QrmiLogCallback) (const char *level, const char *target, const char *message)
typedef QrmiEnvironmentVariables QrmiConfigMap

Enumerations

enum  QrmiReturnCode {
  QRMI_RETURN_CODE_SUCCESS = 0 , QRMI_RETURN_CODE_ERROR = 100 , QRMI_RETURN_CODE_NULL_POINTER_ERROR = 101 , QRMI_RETURN_CODE_ENV_VAR_NOT_SET_ERROR = 102 ,
  QRMI_RETURN_CODE_PARSE_ERROR = 103 , QRMI_RETURN_CODE_UNSUPPORTED_RESOURCE_TYPE_ERROR = 104 , QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR = 105 , QRMI_RETURN_CODE_UNSUPPORTED_PAYLOAD_ERROR = 106 ,
  QRMI_RETURN_CODE_TASK_NOT_READY_ERROR = 107 , QRMI_RETURN_CODE_MISSING_CONFIG_KEY_ERROR = 108 , QRMI_RETURN_CODE_INVALID_INPUT_ERROR = 109 , QRMI_RETURN_CODE_RESOURCE_NOT_FOUND_ERROR = 111 ,
  QRMI_RETURN_CODE_TASK_NOT_FOUND_ERROR = 112 , QRMI_RETURN_CODE_AUTHENTICATION_FAILED_ERROR = 113 , QRMI_RETURN_CODE_INVALID_CONFIG_ERROR = 114
}
enum  QrmiResourceType {
  QRMI_RESOURCE_TYPE_IBM_QUANTUM_SYSTEM , QRMI_RESOURCE_TYPE_QISKIT_RUNTIME_SERVICE , QRMI_RESOURCE_TYPE_IBM_QUANTUM_COMPUTE_SERVICE , QRMI_RESOURCE_TYPE_PASQAL_CLOUD ,
  QRMI_RESOURCE_TYPE_PASQAL_LOCAL , QRMI_RESOURCE_TYPE_ALICE_BOB_FELIS , QRMI_RESOURCE_TYPE_IQM_SERVER , QRMI_RESOURCE_TYPE_OQTOPUS ,
  QRMI_RESOURCE_TYPE_MAESTRO_LOCAL
}
enum  QrmiResourceStatusCode { QRMI_RESOURCE_STATUS_CODE_ONLINE , QRMI_RESOURCE_STATUS_CODE_OFFLINE , QRMI_RESOURCE_STATUS_CODE_PAUSED }
enum  QrmiTaskStatus {
  QRMI_TASK_STATUS_QUEUED , QRMI_TASK_STATUS_RUNNING , QRMI_TASK_STATUS_COMPLETED , QRMI_TASK_STATUS_FAILED ,
  QRMI_TASK_STATUS_CANCELLED
}
enum  QrmiPayload_Tag {
  QRMI_PAYLOAD_QISKIT_PRIMITIVE , QRMI_PAYLOAD_PASQAL_CLOUD , QRMI_PAYLOAD_ALICE_BOB_FELIS , QRMI_PAYLOAD_IQM_SERVER ,
  QRMI_PAYLOAD_OQTOPUS , QRMI_PAYLOAD_MAESTRO_LOCAL
}

Functions

QrmiReturnCode qrmi_log_callback_set (QrmiLogCallback callback)
QrmiReturnCode qrmi_string_free (char *ptr)
QrmiReturnCode qrmi_string_array_free (size_t size, char *array[])
QrmiConfig * qrmi_config_load (const char *filename)
QrmiReturnCode qrmi_config_free (QrmiConfig *ptr)
QrmiResourceDef * qrmi_config_resource_def_get (QrmiConfig *config, const char *resource_id)
const char * qrmi_config_resource_type_to_str (QrmiResourceType type)
QrmiReturnCode qrmi_config_resource_type_from_str (const char *type_str, QrmiResourceType *outp)
QrmiReturnCode qrmi_config_resource_def_free (QrmiResourceDef *ptr)
QrmiReturnCode qrmi_config_resource_names_get (QrmiConfig *config, size_t *num_names, char **names[])
char * qrmi_get_last_error (void)
QrmiReturnCode qrmi_get_last_error_kind (void)
QrmiQuantumResource * qrmi_resource_new (const char *resource_id, QrmiResourceType resource_type)
QrmiQuantumResource * qrmi_resource_new_from_config (const char *resource_id, QrmiResourceType resource_type, const QrmiConfigMap *config)
QrmiReturnCode qrmi_resource_free (QrmiQuantumResource *ptr)
QrmiReturnCode qrmi_resource_is_accessible (QrmiQuantumResource *qrmi, bool *outp)
QrmiReturnCode qrmi_resource_status (QrmiQuantumResource *qrmi, QrmiResourceStatus **outp)
QrmiReturnCode qrmi_resource_status_free (QrmiResourceStatus *ptr)
QrmiReturnCode qrmi_resource_status_code (QrmiResourceStatus *status, QrmiResourceStatusCode *outp)
const char * qrmi_resource_status_code_to_string (QrmiResourceStatusCode code)
char * qrmi_resource_status_reason (QrmiResourceStatus *status)
QrmiReturnCode qrmi_resource_status_healthy (QrmiResourceStatus *status, bool *outp)
QrmiReturnCode qrmi_resource_status_busy (QrmiResourceStatus *status, bool *outp)
QrmiReturnCode qrmi_resource_status_pending_job_count (QrmiResourceStatus *status, uint64_t *outp)
QrmiReturnCode qrmi_resource_status_capacity (QrmiResourceStatus *status, QrmiResourceCapacity **outp)
QrmiReturnCode qrmi_resource_capacity_free (QrmiResourceCapacity *ptr)
QrmiReturnCode qrmi_resource_id (QrmiQuantumResource *qrmi, char **outp)
QrmiReturnCode qrmi_resource_type (QrmiQuantumResource *qrmi, QrmiResourceType *outp)
QrmiReturnCode qrmi_resource_acquire (QrmiQuantumResource *qrmi, char **acquisition_token)
QrmiReturnCode qrmi_resource_release (QrmiQuantumResource *qrmi, const char *acquisition_token)
QrmiReturnCode qrmi_resource_task_start (QrmiQuantumResource *qrmi, const QrmiPayload *payload, char **task_id)
QrmiReturnCode qrmi_resource_task_stop (QrmiQuantumResource *qrmi, const char *task_id)
QrmiReturnCode qrmi_resource_task_status (QrmiQuantumResource *qrmi, const char *task_id, QrmiTaskStatus *status)
QrmiReturnCode qrmi_resource_task_result (QrmiQuantumResource *qrmi, const char *task_id, char **outp)
QrmiReturnCode qrmi_resource_task_logs (QrmiQuantumResource *qrmi, const char *task_id, char **outp)
QrmiReturnCode qrmi_resource_target (QrmiQuantumResource *qrmi, char **outp)
QrmiReturnCode qrmi_resource_metadata (QrmiQuantumResource *qrmi, QrmiResourceMetadata **outp)
QrmiReturnCode qrmi_resource_metadata_free (QrmiResourceMetadata *ptr)
char * qrmi_resource_metadata_value (QrmiResourceMetadata *metadata, const char *key)
QrmiReturnCode qrmi_resource_metadata_keys (QrmiResourceMetadata *metadata, size_t *num_keys, char **key_names[])
QrmiResourceProvider * qrmi_provider_new (QrmiResourceType resource_type, const QrmiEnvironmentVariables *environments)
QrmiReturnCode qrmi_provider_free (QrmiResourceProvider *ptr)
QrmiReturnCode qrmi_provider_resources (QrmiResourceProvider *provider, const char *filters, QrmiQuantumResources *resources_out)
QrmiReturnCode qrmi_provider_resources_free (QrmiQuantumResources *resources)
QrmiReturnCode qrmi_provider_least_busy (QrmiResourceProvider *provider, const char *filters, QrmiQuantumResource **resource_out)
QrmiReturnCode qrmi_service_resources (QrmiQuantumResources *resources_out)
QrmiReturnCode qrmi_service_resources_free (QrmiQuantumResources *resources)

Typedef Documentation

◆ QrmiConfig

typedef struct QrmiConfig QrmiConfig

QRMI configuration file

Example

_run
use qrmi::models::Config;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = Config::load("./qrmi_example_config.json")?;
if let Some(resource) = config.resource_map.get("ibm_osaka") {
println!("Found resource: {}", resource.name);
println!("Type: {:?}", resource.r#type);
for (key, value) in &resource.environment {
println!("Environment variable: {}={}", key, value);
}
}
# Ok(())
# }

◆ QrmiConfigMap

Type alias for key-value map

◆ QrmiLogCallback

typedef void(* QrmiLogCallback) (const char *level, const char *target, const char *message)

C ABI type for qrmi_log_callback_set. This is a C-facing detail: it does not appear anywhere in common.rs, which only knows about plain Rust closures (see common::LogSink). qrmi_log_callback_set below adapts one of these into a LogSink at registration time.

◆ QrmiQuantumResource

Quantum resource handle

◆ QrmiResourceMetadata

Quantum resource metadata

◆ QrmiResourceProvider

Resource provider handle.

◆ QrmiResourceStatus

Quantum resource status

Enumeration Type Documentation

◆ QrmiPayload_Tag

Enumerator
QRMI_PAYLOAD_QISKIT_PRIMITIVE 

Payload that contains Qiskit Primitive input.

QRMI_PAYLOAD_PASQAL_CLOUD 

Payload for Pasqal Cloud and Pasqal Local resources

QRMI_PAYLOAD_ALICE_BOB_FELIS 
QRMI_PAYLOAD_IQM_SERVER 

Payload for IQM Server

QRMI_PAYLOAD_OQTOPUS 

Payload for OQTOPUS Cloud

QRMI_PAYLOAD_MAESTRO_LOCAL 

Payload for Maestro Local Server

321 {
322 /**
323 * Payload that contains Qiskit Primitive input.
324 */
326 /**
327 * Payload for Pasqal Cloud and Pasqal Local resources
328 */
331 /**
332 * Payload for IQM Server
333 */
335 /**
336 * Payload for OQTOPUS Cloud
337 */
339 /**
340 * Payload for Maestro Local Server
341 */
QrmiPayload_Tag
Definition qrmi.h:321
@ QRMI_PAYLOAD_ALICE_BOB_FELIS
Definition qrmi.h:330
@ QRMI_PAYLOAD_MAESTRO_LOCAL
Definition qrmi.h:342
@ QRMI_PAYLOAD_QISKIT_PRIMITIVE
Definition qrmi.h:325
@ QRMI_PAYLOAD_PASQAL_CLOUD
Definition qrmi.h:329
@ QRMI_PAYLOAD_OQTOPUS
Definition qrmi.h:338
@ QRMI_PAYLOAD_IQM_SERVER
Definition qrmi.h:334

◆ QrmiResourceStatusCode

Resource statuses.

Enumerator
QRMI_RESOURCE_STATUS_CODE_ONLINE 

Online and available.

QRMI_RESOURCE_STATUS_CODE_OFFLINE 

Offline and unavailable.

QRMI_RESOURCE_STATUS_CODE_PAUSED 

Online but not currently accepting/running jobs due to a maintenance-type event (e.g. calibration),

158 {
159 /**
160 * Online and available.
161 */
163 /**
164 * Offline and unavailable.
165 */
167 /**
168 * Online but not currently accepting/running jobs due to a
169 * maintenance-type event (e.g. calibration),
170 */
QrmiResourceStatusCode
Definition qrmi.h:158
@ QRMI_RESOURCE_STATUS_CODE_PAUSED
Definition qrmi.h:171
@ QRMI_RESOURCE_STATUS_CODE_ONLINE
Definition qrmi.h:162
@ QRMI_RESOURCE_STATUS_CODE_OFFLINE
Definition qrmi.h:166

◆ QrmiResourceType

QRMI resource types

Enumerator
QRMI_RESOURCE_TYPE_IBM_QUANTUM_SYSTEM 

IBM Quantum System

QRMI_RESOURCE_TYPE_QISKIT_RUNTIME_SERVICE 

Qiskit Runtime Service(deprecated)

QRMI_RESOURCE_TYPE_IBM_QUANTUM_COMPUTE_SERVICE 

IBM Quantum Compute Service

QRMI_RESOURCE_TYPE_PASQAL_CLOUD 

Pasqal Cloud

QRMI_RESOURCE_TYPE_PASQAL_LOCAL 
QRMI_RESOURCE_TYPE_ALICE_BOB_FELIS 

Alice Bob Felis

QRMI_RESOURCE_TYPE_IQM_SERVER 
QRMI_RESOURCE_TYPE_OQTOPUS 
QRMI_RESOURCE_TYPE_MAESTRO_LOCAL 

Maestro Local

125 {
126 /**
127 * IBM Quantum System
128 */
130 /**
131 * Qiskit Runtime Service(deprecated)
132 */
134 /**
135 * IBM Quantum Compute Service
136 */
138 /**
139 * Pasqal Cloud
140 */
143 /**
144 * Alice Bob Felis
145 */
149 /**
150 * Maestro Local
151 */
QrmiResourceType
Definition qrmi.h:125
@ QRMI_RESOURCE_TYPE_IBM_QUANTUM_SYSTEM
Definition qrmi.h:129
@ QRMI_RESOURCE_TYPE_QISKIT_RUNTIME_SERVICE
Definition qrmi.h:133
@ QRMI_RESOURCE_TYPE_OQTOPUS
Definition qrmi.h:148
@ QRMI_RESOURCE_TYPE_IQM_SERVER
Definition qrmi.h:147
@ QRMI_RESOURCE_TYPE_MAESTRO_LOCAL
Definition qrmi.h:152
@ QRMI_RESOURCE_TYPE_IBM_QUANTUM_COMPUTE_SERVICE
Definition qrmi.h:137
@ QRMI_RESOURCE_TYPE_ALICE_BOB_FELIS
Definition qrmi.h:146
@ QRMI_RESOURCE_TYPE_PASQAL_LOCAL
Definition qrmi.h:142
@ QRMI_RESOURCE_TYPE_PASQAL_CLOUD
Definition qrmi.h:141

◆ QrmiReturnCode

Integer return codes returned to C.

Enumerator
QRMI_RETURN_CODE_SUCCESS 

Success.

QRMI_RETURN_CODE_ERROR 

Error. Generic/uncategorized failure – see qrmi_get_last_error() for the message and qrmi_get_last_error_kind() for a more specific machine-readable reason when available.

QRMI_RETURN_CODE_NULL_POINTER_ERROR 

Unexpected null pointer.

QRMI_RETURN_CODE_ENV_VAR_NOT_SET_ERROR 

A required environment variable was not set.

QRMI_RETURN_CODE_PARSE_ERROR 

A configuration value could not be parsed.

QRMI_RETURN_CODE_UNSUPPORTED_RESOURCE_TYPE_ERROR 

Dynamic discovery was requested for an unsupported resource type.

QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR 

The requested operation is not supported by this resource.

QRMI_RETURN_CODE_UNSUPPORTED_PAYLOAD_ERROR 

The payload variant is not supported by this backend.

QRMI_RETURN_CODE_TASK_NOT_READY_ERROR 

The task is not in a state that allows the requested operation.

QRMI_RETURN_CODE_MISSING_CONFIG_KEY_ERROR 

A required key was missing from a provider's environment variable map.

QRMI_RETURN_CODE_INVALID_INPUT_ERROR 

A value was invalid, whether QRMI itself rejected it locally or a vendor's API rejected the resulting request after receiving it.

QRMI_RETURN_CODE_RESOURCE_NOT_FOUND_ERROR 

The named resource (e.g. a backend) does not exist.

QRMI_RETURN_CODE_TASK_NOT_FOUND_ERROR 

The named task (e.g. a job) does not exist, or has already been removed.

QRMI_RETURN_CODE_AUTHENTICATION_FAILED_ERROR 

The request's credentials were missing or rejected.

QRMI_RETURN_CODE_INVALID_CONFIG_ERROR 

A configuration value (or combination of values) was invalid.

55 {
56 /**
57 * Success.
58 */
60 /**
61 * Error. Generic/uncategorized failure -- see `qrmi_get_last_error()`
62 * for the message and `qrmi_get_last_error_kind()` for a more specific
63 * machine-readable reason when available.
64 */
66 /**
67 * Unexpected null pointer.
68 */
70 /**
71 * A required environment variable was not set.
72 */
74 /**
75 * A configuration value could not be parsed.
76 */
78 /**
79 * Dynamic discovery was requested for an unsupported resource type.
80 */
82 /**
83 * The requested operation is not supported by this resource.
84 */
86 /**
87 * The payload variant is not supported by this backend.
88 */
90 /**
91 * The task is not in a state that allows the requested operation.
92 */
94 /**
95 * A required key was missing from a provider's environment variable map.
96 */
98 /**
99 * A value was invalid, whether QRMI itself rejected it locally or a
100 * vendor's API rejected the resulting request after receiving it.
101 */
103 /**
104 * The named resource (e.g. a backend) does not exist.
105 */
107 /**
108 * The named task (e.g. a job) does not exist, or has already been
109 * removed.
110 */
112 /**
113 * The request's credentials were missing or rejected.
114 */
116 /**
117 * A configuration value (or combination of values) was invalid.
118 */
QrmiReturnCode
Definition qrmi.h:55
@ QRMI_RETURN_CODE_PARSE_ERROR
Definition qrmi.h:77
@ QRMI_RETURN_CODE_MISSING_CONFIG_KEY_ERROR
Definition qrmi.h:97
@ QRMI_RETURN_CODE_UNSUPPORTED_RESOURCE_TYPE_ERROR
Definition qrmi.h:81
@ QRMI_RETURN_CODE_UNSUPPORTED_PAYLOAD_ERROR
Definition qrmi.h:89
@ QRMI_RETURN_CODE_AUTHENTICATION_FAILED_ERROR
Definition qrmi.h:115
@ QRMI_RETURN_CODE_RESOURCE_NOT_FOUND_ERROR
Definition qrmi.h:106
@ QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR
Definition qrmi.h:85
@ QRMI_RETURN_CODE_INVALID_CONFIG_ERROR
Definition qrmi.h:119
@ QRMI_RETURN_CODE_NULL_POINTER_ERROR
Definition qrmi.h:69
@ QRMI_RETURN_CODE_ERROR
Definition qrmi.h:65
@ QRMI_RETURN_CODE_TASK_NOT_READY_ERROR
Definition qrmi.h:93
@ QRMI_RETURN_CODE_INVALID_INPUT_ERROR
Definition qrmi.h:102
@ QRMI_RETURN_CODE_SUCCESS
Definition qrmi.h:59
@ QRMI_RETURN_CODE_TASK_NOT_FOUND_ERROR
Definition qrmi.h:111
@ QRMI_RETURN_CODE_ENV_VAR_NOT_SET_ERROR
Definition qrmi.h:73

◆ QrmiTaskStatus

Task statuses.

Enumerator
QRMI_TASK_STATUS_QUEUED 

Task is queued

QRMI_TASK_STATUS_RUNNING 

Task is running

QRMI_TASK_STATUS_COMPLETED 

Task was completed

QRMI_TASK_STATUS_FAILED 

Task was failed

QRMI_TASK_STATUS_CANCELLED 

Task was cancelled

177 {
178 /**
179 * Task is queued
180 */
182 /**
183 * Task is running
184 */
186 /**
187 * Task was completed
188 */
190 /**
191 * Task was failed
192 */
194 /**
195 * Task was cancelled
196 */
QrmiTaskStatus
Definition qrmi.h:177
@ QRMI_TASK_STATUS_CANCELLED
Definition qrmi.h:197
@ QRMI_TASK_STATUS_QUEUED
Definition qrmi.h:181
@ QRMI_TASK_STATUS_COMPLETED
Definition qrmi.h:189
@ QRMI_TASK_STATUS_FAILED
Definition qrmi.h:193
@ QRMI_TASK_STATUS_RUNNING
Definition qrmi.h:185

Function Documentation

◆ qrmi_get_last_error_kind()

QrmiReturnCode qrmi_get_last_error_kind ( void )

Returns a machine-readable classification of the most recent error encountered during an API call, complementing qrmi_get_last_error()'s human-readable message. Unlike qrmi_get_last_error(), this value is NOT cleared after being read, since callers typically check it before (or without) reading the message.

If no QRMI-specific error has been recorded (e.g. the failure came from an unrelated source, or no error has occurred yet), this returns QRMI_RETURN_CODE_ERROR – the generic code – as a safe default.

Returns
A ReturnCode describing the kind of the most recent error.
Version
0.16.0

◆ qrmi_resource_capacity_free()

QrmiReturnCode qrmi_resource_capacity_free ( QrmiResourceCapacity * ptr)

Frees a QrmiResourceCapacity handle returned by qrmi_resource_status_capacity().

Safety

  • ptr must have been returned by a previous call to qrmi_resource_status_capacity(). Otherwise, or if ptr has already been freed, undefined behavior occurs.
QrmiResourceCapacity *capacity = NULL;
printf("available_slots=%u\n", capacity->available_slots);
}
QrmiReturnCode qrmi_resource_status_capacity(QrmiResourceStatus *status, QrmiResourceCapacity **outp)
QrmiReturnCode qrmi_resource_capacity_free(QrmiResourceCapacity *ptr)
Definition qrmi.h:310
uint64_t available_slots
Definition qrmi.h:314
Parameters
(ptr)[in] A QrmiResourceCapacity handle to be freed
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.25.0

◆ qrmi_resource_status_busy()

QrmiReturnCode qrmi_resource_status_busy ( QrmiResourceStatus * status,
bool * outp )

Returns whether the resource is currently busy.

Safety

QrmiResourceStatus *status = NULL;
bool busy = false;
rc = qrmi_resource_status_busy(status, &busy);
printf("busy=%d\n", busy);
printf("this vendor does not report busy information\n");
} else {
printf("qrmi_resource_status_busy() failed: %s\n", qrmi_get_last_error());
}
}
QrmiReturnCode qrmi_resource_status(QrmiQuantumResource *qrmi, QrmiResourceStatus **outp)
char * qrmi_get_last_error(void)
struct QrmiResourceStatus QrmiResourceStatus
Definition qrmi.h:242
QrmiReturnCode qrmi_resource_status_free(QrmiResourceStatus *ptr)
QrmiReturnCode qrmi_resource_status_busy(QrmiResourceStatus *status, bool *outp)
Parameters
(status)[in] A QrmiResourceStatus handle
(outp)[out] Whether the resource is busy
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded. QrmiReturnCode::QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR if the vendor does not report health information.
Version
0.25.0

◆ qrmi_resource_status_capacity()

QrmiReturnCode qrmi_resource_status_capacity ( QrmiResourceStatus * status,
QrmiResourceCapacity ** outp )

Returns the resource's capacity information, if reported.

Safety

QrmiResourceCapacity *capacity = NULL;
printf("available_slots=%u\n", capacity->available_slots);
}
Parameters
(status)[in] A QrmiResourceStatus handle
(outp)[out] Capacity handle if succeeded. Must call qrmi_resource_capacity_free() to free if no longer used.
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded. QrmiReturnCode::QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR if the vendor does not report capacity information.
Version
0.25.0

◆ qrmi_resource_status_code()

QrmiReturnCode qrmi_resource_status_code ( QrmiResourceStatus * status,
QrmiResourceStatusCode * outp )

Returns the resource's status code (Online/Offline/Paused).

Safety

QrmiResourceStatus *status = NULL;
rc = qrmi_resource_status_code(status, &code);
switch (code) {
printf("online\n");
break;
printf("offline\n");
break;
printf("paused\n");
break;
case QRMI_RESOURCE_STATUS_CODE_BUSY:
printf("busy\n");
break;
}
}
}
QrmiReturnCode qrmi_resource_status_code(QrmiResourceStatus *status, QrmiResourceStatusCode *outp)
Parameters
(status)[in] A QrmiResourceStatus handle
(outp)[out] The status code
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.25.0

◆ qrmi_resource_status_code_to_string()

const char * qrmi_resource_status_code_to_string ( QrmiResourceStatusCode code)

Converts a QrmiResourceStatusCode value to a human-readable, lowercase string ("online", "offline", "paused"). Intended for logging and diagnostic output.

Example

printf("status=%s\n", qrmi_resource_status_code_to_string(code));
}
const char * qrmi_resource_status_code_to_string(QrmiResourceStatusCode code)
Parameters
(code)[in] A QrmiResourceStatusCode value
Returns
A statically-allocated, human-readable string. Must NOT be freed and remains valid for the lifetime of the program.
Version
0.25.0

◆ qrmi_resource_status_free()

QrmiReturnCode qrmi_resource_status_free ( QrmiResourceStatus * ptr)

Frees the memory space pointed to by ptr, which must have been returned by a previous call to qrmi_resource_status(). Otherwise, or if ptr has already been freed, segmentation fault occurs. If ptr is NULL, returns < 0.

Safety

Example

Parameters
(ptr)[in] A QrmiResourceStatus handle to be free
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded.
Version
0.25.0

◆ qrmi_resource_status_healthy()

QrmiReturnCode qrmi_resource_status_healthy ( QrmiResourceStatus * status,
bool * outp )

Returns whether the resource is currently healthy.

Safety

QrmiResourceStatus *status = NULL;
bool healthy = false;
rc = qrmi_resource_status_healthy(status, &healthy);
printf("healthy=%d\n", healthy);
printf("this vendor does not report health information\n");
} else {
printf("qrmi_resource_status_healthy() failed: %s\n", qrmi_get_last_error());
}
}
QrmiReturnCode qrmi_resource_status_healthy(QrmiResourceStatus *status, bool *outp)
Parameters
(status)[in] A QrmiResourceStatus handle
(outp)[out] Whether the resource is healthy
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded. QrmiReturnCode::QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR if the vendor does not report health information.
Version
0.25.0

◆ qrmi_resource_status_pending_job_count()

QrmiReturnCode qrmi_resource_status_pending_job_count ( QrmiResourceStatus * status,
uint64_t * outp )

Returns the number of jobs pending in the queue.

Safety

QrmiResourceStatus *status = NULL;
uint64_t pending_job_count = 0;
rc = qrmi_resource_status_pending_job_count(status, &pending_job_count);
printf("pending_job_count=%llu\n", (unsigned long long)pending_job_count);
printf("this resource has no queue / does not report pending job count\n");
} else {
printf("qrmi_resource_status_pending_job_count() failed: %s\n", qrmi_get_last_error());
}
}
QrmiReturnCode qrmi_resource_status_pending_job_count(QrmiResourceStatus *status, uint64_t *outp)
Parameters
(status)[in] A QrmiResourceStatus handle
(outp)[out] Number of pending jobs
Returns
QrmiReturnCode::QRMI_RETURN_CODE_SUCCESS if succeeded. QrmiReturnCode::QRMI_RETURN_CODE_UNSUPPORTED_FUNCTION_ERROR if the resource has no queue / the vendor does not report this.
Version
0.25.0

◆ qrmi_resource_status_reason()

char * qrmi_resource_status_reason ( QrmiResourceStatus * status)

Returns the vendor-specific status reason (e.g. "maintenance", "calibration"), if reported.

Safety

QrmiResourceStatus *status = NULL;
char *reason = qrmi_resource_status_reason(status);
if (reason != NULL) {
printf("reason=%s\n", reason);
} else {
printf("no status reason reported\n");
}
}
QrmiReturnCode qrmi_string_free(char *ptr)
char * qrmi_resource_status_reason(QrmiResourceStatus *status)
Parameters
(status)[in] A QrmiResourceStatus handle
Returns
status reason string if the vendor reported one. Must call qrmi_string_free() to free if no longer used. Returns NULL if status is NULL or the vendor did not report a reason.
Version
0.25.0