Definition of SDK interfaces. More...

#include <stdlib.h>
#include <stdint.h>
#include <sys/types.h>

Data Structures
struct	gg_request_result
	Describes result metadata after request is made. More...

struct	gg_lambda_context
	Describes context when lambda handler is called. More...

struct	gg_invoke_options
	Describes the options to invoke a target lambda. More...

Typedefs
typedef enum gg_error	gg_error
	Greengrass SDK error enum. More...

typedef struct _gg_request *	gg_request

typedef enum gg_request_status	gg_request_status
	Greengrass SDK request status enum. More...

typedef struct gg_request_result	gg_request_result
	Describes result metadata after request is made. More...

typedef struct gg_lambda_context	gg_lambda_context
	Describes context when lambda handler is called. More...

typedef enum gg_invoke_type	gg_invoke_type
	Describes invocation type for lambda function.

typedef enum gg_runtime_opt	gg_runtime_opt
	Flags set for the gg_runtime_start)(.., opt)

typedef struct gg_invoke_options	gg_invoke_options
	Describes the options to invoke a target lambda. More...

typedef enum gg_queue_full_policy_options	gg_queue_full_policy_options
	Describes the policy options to take when Greengrass's queue is full.

typedef struct _gg_publish_options *	gg_publish_options

typedef enum gg_log_level	gg_log_level
	Describes log levels could used in gg_log()

typedef void(*	gg_lambda_handler) (const gg_lambda_context *cxt)
	Handler signature that will be called whenever a subscribed message is received. More...

Enumerations
enum	gg_error { GGE_SUCCESS = 0, GGE_OUT_OF_MEMORY, GGE_INVALID_PARAMETER, GGE_INVALID_STATE, GGE_INTERNAL_FAILURE, GGE_TERMINATE, GGE_RESERVED_MAX, GGE_RESERVED_PAD = 0x7FFFFFFF }
	Greengrass SDK error enum. More...

enum	gg_request_status { GG_REQUEST_SUCCESS = 0, GG_REQUEST_HANDLED, GG_REQUEST_UNHANDLED, GG_REQUEST_UNKNOWN, GG_REQUEST_AGAIN, GG_REQUEST_RESERVED_MAX, GG_REQUEST_RESERVED_PAD = 0x7FFFFFFF }
	Greengrass SDK request status enum. More...

enum	gg_invoke_type { GG_INVOKE_EVENT, GG_INVOKE_REQUEST_RESPONSE, GG_INVOKE_RESERVED_MAX, GG_INVOKE_RESERVED_PAD = 0x7FFFFFFF }
	Describes invocation type for lambda function. More...

enum	gg_runtime_opt { GG_RT_OPT_ASYNC = 0x1, GG_RT_OPT_RESERVED_PAD = 0x7FFFFFFF }
	Flags set for the gg_runtime_start)(.., opt) More...

enum	gg_queue_full_policy_options { GG_QUEUE_FULL_POLICY_BEST_EFFORT, GG_QUEUE_FULL_POLICY_ALL_OR_ERROR, GG_QUEUE_FULL_POLICY_RESERVED_MAX, GG_QUEUE_FULL_POLICY_RESERVED_PAD = 0x7FFFFFFF }
	Describes the policy options to take when Greengrass's queue is full. More...

enum	gg_log_level { GG_LOG_RESERVED_NOTSET, GG_LOG_DEBUG, GG_LOG_INFO, GG_LOG_WARN, GG_LOG_ERROR, GG_LOG_FATAL, GG_LOG_RESERVED_MAX, GG_LOG_RESERVED_PAD = 0x7FFFFFFF }
	Describes log levels could used in gg_log() More...

Functions
gg_error	gg_global_init (uint32_t opt)
	Initialize Greengrass internal global variables. More...

gg_error	gg_log (gg_log_level level, const char *format,...)
	Log message to Greengrass Core using similar syntax to printf. More...

gg_error	gg_request_init (gg_request *ggreq)
	Initialize the context for managing the request. More...

gg_error	gg_request_close (gg_request ggreq)
	Close a request context that was created by gg_request_init. More...

gg_error	gg_request_read (gg_request ggreq, void buffer, size_t buffer_size, size_t amount_read)
	Read the data from a request. This method should be called till amount_read is zero. More...

gg_error	gg_runtime_start (gg_lambda_handler handler, uint32_t opt)
	Registers the lambda handler and start Greengrass lambda runtime. More...

gg_error	gg_lambda_handler_read (void buffer, size_t buffer_size, size_t amount_read)
	Read the data from the invoker of the lambda. This method should be called till amount_read is zero. More...

gg_error	gg_lambda_handler_write_response (const void *response, size_t response_size)
	Write response to the invoker of the lambda. More...

gg_error	gg_lambda_handler_write_error (const char *error_message)
	Write error message to the invoker of the lambda. More...

gg_error	gg_get_secret_value (gg_request ggreq, const char secret_id, const char version_id, const char version_stage, gg_request_result result)
	Get secret value for the given secret. More...

gg_error	gg_invoke (gg_request ggreq, const gg_invoke_options opts, gg_request_result result)
	Invoke a lambda with an optional payload. More...

gg_error	gg_publish_options_init (gg_publish_options *opts)
	Initialize the publish options. More...

gg_error	gg_publish_options_free (gg_publish_options opts)
	Free a publish options that was created by gg_publish_options_init. More...

gg_error	gg_publish_options_set_queue_full_policy (gg_publish_options opts, gg_queue_full_policy_options policy)
	Sets the queue full policy on a publish options. More...

gg_error	gg_publish_with_options (gg_request ggreq, const char topic, const void payload, size_t payload_size, const gg_publish_options opts, gg_request_result *result)
	Publish a payload to a topic. More...

gg_error	gg_publish (gg_request ggreq, const char topic, const void payload, size_t payload_size, gg_request_result *result)
	Publish a payload to a topic. More...

gg_error	gg_get_thing_shadow (gg_request ggreq, const char thing_name, gg_request_result result)
	Get thing shadow for thing name. More...

gg_error	gg_update_thing_shadow (gg_request ggreq, const char thing_name, const char update_payload, gg_request_result *result)
	Update thing shadow for thing name. More...

gg_error	gg_delete_thing_shadow (gg_request ggreq, const char thing_name, gg_request_result result)
	Delete thing shadow for thing name. More...

Detailed Description

Typedef Documentation

typedef enum gg_error gg_error

Enumeration of return values from the gg_* functions within the SDK.

typedef struct gg_invoke_options gg_invoke_options

Parameters

function_arn	Null-terminated string full lambda ARN to be invoked
customer_context	base64-encoded null-terminated json string
qualifier	Null-terminated string version of the function
type	Specifiy whether a response is needed
payload	Buffer to be sent to the invoked lambda
payload_size	Size of payload buffer

typedef struct gg_lambda_context gg_lambda_context

Parameters

function_arn	Null-terminated string full lambda ARN
client_context	Null-terminated string of client context

typedef void(* gg_lambda_handler) (const gg_lambda_context *cxt)

Parameters

cxt	Details about the lambda invocation

typedef struct gg_request_result gg_request_result

Parameters

request_status the request status

typedef enum gg_request_status gg_request_status

Enumeration of status populated when gg_invoke(), gg_publish() or gg_xxx_thing_shadow() function is called.

Enumeration Type Documentation

enum gg_error

Enumeration of return values from the gg_* functions within the SDK.

Enumerator
GGE_SUCCESS	Returned when success
GGE_OUT_OF_MEMORY	Returned when process is out of memory
GGE_INVALID_PARAMETER	Returned when input parameter is invalid
GGE_INVALID_STATE	Returned when SDK is in an invalid state
GGE_INTERNAL_FAILURE	Returned when SDK encounters internal failure
GGE_TERMINATE	Returned when process gets signal to terminate

enum gg_invoke_type

Enumerator
GG_INVOKE_EVENT	Invoke the function asynchronously
GG_INVOKE_REQUEST_RESPONSE	Invoke the function synchronously (default)

enum gg_log_level

Enumerator
GG_LOG_DEBUG	Debug
GG_LOG_INFO	Info
GG_LOG_WARN	Warn
GG_LOG_ERROR	Error
GG_LOG_FATAL	Fatal. System will exist

enum gg_queue_full_policy_options

Enumerator
GG_QUEUE_FULL_POLICY_BEST_EFFORT	GGC will deliver messages to as many targets as possible
GG_QUEUE_FULL_POLICY_ALL_OR_ERROR	GGC will either deliver messages to all targets and return request status GG_REQUEST_SUCCESS or deliver to no targets and return a request status GG_REQUEST_AGAIN

enum gg_request_status

Enumeration of status populated when gg_invoke(), gg_publish() or gg_xxx_thing_shadow() function is called.

Enumerator
GG_REQUEST_SUCCESS	function call returns expected payload type
GG_REQUEST_HANDLED	function call is successfull, however lambda responss with an error
GG_REQUEST_UNHANDLED	function call is unsuccessfull, lambda exits abnormally
GG_REQUEST_UNKNOWN	System encounters unknown error. Check logs for more details
GG_REQUEST_AGAIN	function call is throttled, try again

enum gg_runtime_opt

Enumerator
GG_RT_OPT_ASYNC	Start the runtime in a new thread. Runtime will exit if main thread exits

Function Documentation

gg_error gg_delete_thing_shadow	(	gg_request	ggreq,
		const char *	thing_name,
		gg_request_result *	result
	)

Parameters

ggreq	Provides context about the request
thing_name	Null-terminated string specifying thing shadow to delete
thing_name	Specifies which thing shadow should be deleted
result	Describes the result of the request

Returns: Greengrass error code

gg_error gg_get_secret_value	(	gg_request	ggreq,
		const char *	secret_id,
		const char *	version_id,
		const char *	version_stage,
		gg_request_result *	result
	)

Parameters

ggreq	Provides context about the request
secret_id	Null-terminated string id which secret to get
version_id	Null-terminated string version id which version to get
version_stage	Optional null-terminated string version stage which stage to get
result	Describes the result of the request

Returns: Greengrass error code

gg_error gg_get_thing_shadow	(	gg_request	ggreq,
		const char *	thing_name,
		gg_request_result *	result
	)

Parameters

ggreq	Provides context about the request
thing_name	Null-terminated string specifying thing shadow to get
result	Describes the result of the request

Returns: Greengrass error code

gg_error gg_global_init ( uint32_t opt )

Parameters

opt	Reserved for future use. Must be set to 0.

Returns: Greengrass error code

Note: THIS IS NOT THREAD SAFE and must be called when there is only a single main thread executing. User must call this function before creating any threads. User must call this function before calling any other Greengrass function in this SDK.

gg_error gg_invoke	(	gg_request	ggreq,
		const gg_invoke_options *	opts,
		gg_request_result *	result
	)

Parameters

ggreq	Provides context about the request
opts	Describes the options for invoke
result	Describes the result of the request

Returns: Greengrass error code

gg_error gg_lambda_handler_read	(	void *	buffer,
		size_t	buffer_size,
		size_t *	amount_read
	)

Parameters

buffer	Destination for read data
buffer_size	Size of buffer
amount_read	Destination for amount of data read into buffer

Returns: Greengrass error code

Note: This should only be used in the lambda handler

gg_error gg_lambda_handler_write_error ( const char * error_message )

Parameters

error_message Null-terminated string error message to be written

Returns: Greengrass error code

Note: This should only be used in the lambda handler; The caller's invoke will return result GG_REQUEST_HANDLED in the gg_request_result struct instead of GG_REQUEST_SUCCESS.

gg_error gg_lambda_handler_write_response	(	const void *	response,
		size_t	response_size
	)

Parameters

response	Response data to be written
response_size	Amount of data stored in response

Returns: Greengrass error code

Note: This should only be used in the lambda handler

gg_error gg_log	(	gg_log_level	level,
		const char *	format,
			...
	)

Parameters

level	Level of message that can be filtered based on settings
format	Similar to printf
...	Similar to printf

Returns: Greengrass error code

gg_error gg_publish	(	gg_request	ggreq,
		const char *	topic,
		const void *	payload,
		size_t	payload_size,
		gg_request_result *	result
	)

Parameters

ggreq	Provides context about the request
topic	Null-terminated string topic where to publish the payload
payload	Data to be sent to the topic - caller will free
payload_size	Size of payload buffer
result	Describes the result of the request

Returns: Greengrass error code

Note: Calls gg_publish_with_options with opts==NULL

gg_error gg_publish_options_free ( gg_publish_options opts )

Parameters

opts	Publish options to be freed

Returns: Greengrass error code

gg_error gg_publish_options_init ( gg_publish_options * opts )

Parameters

opts	Pointer to publish options to be initialized

Returns: Greengrass error code

Note: Need to call gg_publish_options_free on opts when done using it

gg_error gg_publish_options_set_queue_full_policy	(	gg_publish_options	opts,
		gg_queue_full_policy_options	policy
	)

Parameters

opts	Publish options to be configured
policy	Selected queue full policy to be set

Returns: Greengrass error code

gg_error gg_publish_with_options	(	gg_request	ggreq,
		const char *	topic,
		const void *	payload,
		size_t	payload_size,
		const gg_publish_options	opts,
		gg_request_result *	result
	)

Parameters

ggreq	Provides context about the request
topic	Null-terminated string topic where to publish the payload
payload	Data to be sent to the topic - caller will free
payload_size	Size of payload buffer
opts	Publish options that configure publish behavior
result	Describes the result of the request

Returns: Greengrass error code

gg_error gg_request_close ( gg_request ggreq )

Parameters

ggreq Context to be closed

Returns: Greengrass error code

gg_error gg_request_init ( gg_request * ggreq )

Parameters

ggreq Pointer to context to be initialized

Returns: Greengrass error code

Note: Need to call gg_request_close on ggreq when done using it

gg_error gg_request_read	(	gg_request	ggreq,
		void *	buffer,
		size_t	buffer_size,
		size_t *	amount_read
	)

Parameters

ggreq	Provides context about the request
buffer	Destination for read data
buffer_size	Size of buffer
amount_read	Destination for amount of data read into buffer

Returns: Greengrass error code

gg_error gg_runtime_start	(	gg_lambda_handler	handler,
		uint32_t	opt
	)

Parameters

handler	Customer lambda code to be run when subscription is triggered
opt	Mask flags of gg_runtime_opt options, 0 for default

Note: Must be called. This uses and will overwrite the SIGTERM handler

gg_error gg_update_thing_shadow	(	gg_request	ggreq,
		const char *	thing_name,
		const char *	update_payload,
		gg_request_result *	result
	)

Parameters

ggreq	Provides context about the request
thing_name	Null-terminated string specifying thing shadow to update
update_payload	Null-terminated string to be updated in the shadow
result	Describes the result of the request

Returns: Greengrass error code

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation