Azure SDK for Embedded C
Data Structures | Typedefs | Functions | Variables
az_context.h File Reference

Context for canceling long running operations. More...

#include <azure/core/az_result.h>
#include <stddef.h>
#include <stdint.h>
#include <azure/core/_az_cfg_prefix.h>
#include <azure/core/_az_cfg_suffix.h>

Go to the source code of this file.

Data Structures

struct  az_context
 A context is a node within a tree that represents expiration times and key/value pairs. More...
 

Typedefs

typedef struct az_context az_context
 A context is a node within a tree that represents expiration times and key/value pairs.
 

Functions

AZ_NODISCARD az_context az_context_create_with_expiration (az_context const *parent, int64_t expiration)
 Creates a new expiring az_context node that is a child of the specified parent. More...
 
AZ_NODISCARD az_context az_context_create_with_value (az_context const *parent, void const *key, void const *value)
 Creates a new key/value az_context node that is a child of the specified parent. More...
 
void az_context_cancel (az_context *ref_context)
 Cancels the specified az_context node; this cancels all the child nodes as well. More...
 
AZ_NODISCARD int64_t az_context_get_expiration (az_context const *context)
 Returns the soonest expiration time of this az_context node or any of its parent nodes. More...
 
AZ_NODISCARD bool az_context_has_expired (az_context const *context, int64_t current_time)
 Returns true if this az_context node or any of its parent nodes' expiration is before the current_time. More...
 
AZ_NODISCARD az_result az_context_get_value (az_context const *context, void const *key, void const **out_value)
 Walks up this az_context node's parents until it find a node whose key matches the specified key and returns the corresponding value. More...
 

Variables

az_context az_context_application
 The application root az_context instances. More...
 

Detailed Description

Context for canceling long running operations.

Note
You MUST NOT use any symbols (macros, functions, structures, enums, etc.) prefixed with an underscore ('_') directly in your application code. These symbols are part of Azure SDK's internal implementation; we do not document these symbols and they are subject to change in future versions of the SDK which would break your code.

Function Documentation

◆ az_context_cancel()

void az_context_cancel ( az_context ref_context)

Cancels the specified az_context node; this cancels all the child nodes as well.

Parameters
[in,out]ref_contextA pointer to the az_context node to be canceled.

◆ az_context_create_with_expiration()

AZ_NODISCARD az_context az_context_create_with_expiration ( az_context const *  parent,
int64_t  expiration 
)

Creates a new expiring az_context node that is a child of the specified parent.

Parameters
[in]parentThe az_context node that is the parent to the new node.
[in]expirationThe time when this new node should be canceled.
Returns
The new child az_context node.

◆ az_context_create_with_value()

AZ_NODISCARD az_context az_context_create_with_value ( az_context const *  parent,
void const *  key,
void const *  value 
)

Creates a new key/value az_context node that is a child of the specified parent.

Parameters
[in]parentThe az_context node that is the parent to the new node.
[in]keyA pointer to the key of this new az_context node.
[in]valueA pointer to the value of this new az_context node.
Returns
The new child az_context node.

◆ az_context_get_expiration()

AZ_NODISCARD int64_t az_context_get_expiration ( az_context const *  context)

Returns the soonest expiration time of this az_context node or any of its parent nodes.

Parameters
[in]contextA pointer to an az_context node.
Returns
The soonest expiration time from this context and its parents.

◆ az_context_get_value()

AZ_NODISCARD az_result az_context_get_value ( az_context const *  context,
void const *  key,
void const **  out_value 
)

Walks up this az_context node's parents until it find a node whose key matches the specified key and returns the corresponding value.

Parameters
[in]contextThe az_context node in the tree where checking starts.
[in]keyA pointer to the key to be scanned for.
[out]out_valueA pointer to a void const* that will receive the key's associated value if the key is found.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKThe key is found.
AZ_ERROR_ITEM_NOT_FOUNDNo nodes are found with the specified key.

◆ az_context_has_expired()

AZ_NODISCARD bool az_context_has_expired ( az_context const *  context,
int64_t  current_time 
)

Returns true if this az_context node or any of its parent nodes' expiration is before the current_time.

Parameters
[in]contextA pointer to the az_context node to check.
[in]current_timeThe current time.

Variable Documentation

◆ az_context_application

az_context az_context_application
extern

The application root az_context instances.

The az_context_application never expires but you can explicitly cancel it by passing its address to az_context_cancel() which effectively cancels all its az_context child nodes.