Publishing

---

Overview

Provides methods and entities to create publishing connections to a project, format data rows and blocks and send the data to the project. For an overview description of publishing refer to PublishingSection.

	Publisher Options
	Publisher Events
	Message Writer
Entities/Objects
typedef struct EspPublisher	EspPublisher
typedef struct EspPublisherOptions	EspPublisherOptions
typedef struct EspPublisherEvent	EspPublisherEvent
typedef void(*	PUBLISHER_CALLBACK_T )(const EspPublisherEvent *event, void *user_data)
typedef struct EspMessageWriter	EspMessageWriter
typedef struct EspRelativeRowWriter	EspRelativeRowWriter

Functions
ESPAPICALL EspPublisher *	esp_publisher_create (const EspUri *uri, const EspCredentials *credentials, const EspPublisherOptions *options, EspError *error)
ESPAPICALL int32_t	esp_publisher_free (EspPublisher *publisher, EspError *error)
ESPAPICALL EspProject *	esp_publisher_get_project (EspPublisher *publisher, EspError *error)
ESPAPICALL int32_t	esp_publisher_connect (EspPublisher *publisher, EspError *error)
ESPAPICALL int32_t	esp_publisher_set_callback (EspPublisher *publisher, uint32_t events, PUBLISHER_CALLBACK_T callback, void *user_data, EspError *error)
ESPAPICALL int32_t	esp_publisher_select_with (EspPublisher *publisher, EspSelector *selector, uint32_t events, EspError *error)
ESPAPICALL int32_t	esp_publisher_disconnect (EspPublisher *publisher, EspError *error)
ESPAPICALL int32_t	esp_publisher_close (EspPublisher *publisher, EspError *error)
ESPAPICALL EspMessageWriter *	esp_publisher_get_writer (EspPublisher *publisher, const EspStream *stream, EspError *error)
ESPAPICALL int32_t	esp_publisher_publish (EspPublisher *publisher, EspMessageWriter *writer, EspError *error)
ESPAPICALL int32_t	esp_publisher_commit (EspPublisher *publisher, EspError *error)

---

Function Documentation

ESPAPICALL int32_t esp_publisher_close	(	EspPublisher *	publisher,
		EspError *	error
	)

Close the publisher. This object will no longer be accessible. In DIRECT access mode the call returns when the publisher is closed. In CALLBACK/SELECT the call will generate an ESP_PUBLISHER_CLOSED event.

Returns:

0 on success.

Parameters:

publisher

EspPublisher to close

ESPAPICALL int32_t esp_publisher_commit	(	EspPublisher *	publisher,
		EspError *	error
	)

Issues a commit call on the publisher which causes the platform to process all its input queues and commit the data to its log stores. If buffering is enabled this call waits until all queued up data is sent.

Returns:

0 on success.

Parameters:

publisher

The publisher whose queues to commit

ESPAPICALL int32_t esp_publisher_connect	(	EspPublisher *	publisher,
		EspError *	error
	)

Connect to the project the publisher will be publishing to. In DIRECT access the call will return when the publisher has connected. In CALLBACK/SELECT the call returns immediately. Completion is indicated by the generation of an ESP_PUBLISHER_CONNECTED event.

Returns:

0 on success.

Parameters:

publisher

EspPublisher to connect

ESPAPICALL EspPublisher* esp_publisher_create	(	const EspUri *	uri,
		const EspCredentials *	credentials,
		const EspPublisherOptions *	options,
		EspError *	error
	)

Create a publisher. The new EspPublisher will need to be freed using esp_publisher_free().

Returns:

NULL on error.

Parameters:

uri	URI of the project this publisher will publish to
credentials	Credentials to use to authenticate, NULL if no authentication
options	Publishing options to use for the new EspPublisher

ESPAPICALL int32_t esp_publisher_disconnect	(	EspPublisher *	publisher,
		EspError *	error
	)

Disconnect the publisher from the project. In DIRECT mode call returns when the publisher has disconnected. In CALLBACK/SELECT will generate an ESP_PUBLISHER_DISCONNECTED event.

Returns:

0 on success.

Parameters:

publisher

EspPublisher to disconnect

ESPAPICALL int32_t esp_publisher_free	(	EspPublisher *	publisher,
		EspError *	error
	)

Frees an EspPublisher created using esp_publisher_create().

Returns:

0 on success.

Parameters:

publisher

EspPublisher to free - must have been created using esp_publisher_create()

ESPAPICALL EspProject* esp_publisher_get_project	(	EspPublisher *	publisher,
		EspError *	error
	)

Retrieve the parent EspProject for this publisher.

Returns:

NULL on error.

Parameters:

publisher

EspProject to which this EspPublisher is publishing

ESPAPICALL EspMessageWriter* esp_publisher_get_writer	(	EspPublisher *	publisher,
		const EspStream *	stream,
		EspError *	error
	)

Retrieve an EspMessageWriter that can be used to build single row or blocked messages to send to the project.

Returns:

NULL on error.

Parameters:

publisher	EspPublisher to use to publish the data
stream	EspStream the message writer will be formatting data for

ESPAPICALL int32_t esp_publisher_publish	(	EspPublisher *	publisher,
		EspMessageWriter *	writer,
		EspError *	error
	)

Publishes the data currently in the passed EspMessageWriter. The actual behavior of this function depends on a number of factors: the access mode, buffering if any and whether synchronous publishing is in effect.

ESPAPICALL int32_t esp_publisher_select_with	(	EspPublisher *	publisher,
		EspSelector *	selector,
		uint32_t	events,
		EspError *	error
	)

Register the EspPublisher with the specified EspSelector object. Use for SELECTION mode access.

Returns:

0 on success.

Parameters:

publisher	EspPublisher to monitor
selector	The EspSelector to use for monitoring
events	bitwise OR'd EspPublisherEvents to monitor for

ESPAPICALL int32_t esp_publisher_set_callback	(	EspPublisher *	publisher,
		uint32_t	events,
		PUBLISHER_CALLBACK_T	callback,
		void *	user_data,
		EspError *	error
	)

Set the callback handler if the publisher was created using CALLBACK access mode.

Returns:

0 on success.

Parameters:

publisher	EspPublisher to monitor
events	bitwised OR'd value of events to monitor
callback	The callback handler function
user_data	This pointer is passed back to the handler function