publisher.h File Reference

OpenTok Publisher. More...

#include "config.h"
#include "stream.h"
#include "video_frame.h"
#include "audio_data.h"
#include "camera_capture_resolution.h"
#include "media_transformer.h"

Go to the source code of this file.

Data Structures
struct	otc_publisher_audio_stats
struct	otc_publisher_video_stats
struct	otc_publisher_callbacks
struct	otc_publisher_rtc_stats
struct	otc_publisher_rtc_stats_report_cb

Typedefs
typedef struct otc_publisher	otc_publisher
typedef struct otc_publisher_settings	otc_publisher_settings

Enumerations
enum	otc_publisher_error_code {   OTC_PUBLISHER_INTERNAL_ERROR = 2000, OTC_PUBLISHER_SESSION_DISCONNECTED, OTC_PUBLISHER_TIMED_OUT = 1541, OTC_PUBLISHER_UNABLE_TO_PUBLISH = 1500,   OTC_PUBLISHER_WEBRTC_ERROR = 1610, OTC_PUBLISHER_ENCRYPTION_INTERNAL_ERROR }
enum	otc_publisher_video_type { OTC_PUBLISHER_VIDEO_TYPE_CAMERA = 1, OTC_PUBLISHER_VIDEO_TYPE_SCREEN = 2 }
enum	otc_media_type { OTC_MEDIA_TYPE_VIDEO = 0, OTC_MEDIA_TYPE_AUDIO }
	Media type.

Functions
otc_publisher *	otc_publisher_new (const char *name, const struct otc_video_capturer_callbacks *capturer, const struct otc_publisher_callbacks *callbacks)
otc_publisher_settings *	otc_publisher_settings_new ()
otc_status	otc_publisher_settings_delete (otc_publisher_settings *settings)
otc_status	otc_publisher_settings_set_name (otc_publisher_settings *settings, const char *name)
otc_status	otc_publisher_settings_set_video_capturer (otc_publisher_settings *settings, const struct otc_video_capturer_callbacks *capturer)
otc_status	otc_publisher_settings_set_audio_track (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_video_track (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_stereo (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_opus_dtx (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_auto_gain_control (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_noise_suppression (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_echo_cancellation (otc_publisher_settings *settings, otc_bool enabled)
otc_status	otc_publisher_settings_set_disable_audio_processing (otc_publisher_settings *settings, otc_bool disabled)
otc_status	otc_publisher_settings_set_default_camera_capture_resolution (otc_publisher_settings *settings, const enum otc_camera_capture_resolution camera_capture_resolution)
otc_status	otc_publisher_settings_set_scalable_screenshare (otc_publisher_settings *settings, const otc_bool enabled)
otc_publisher *	otc_publisher_new_with_settings (const struct otc_publisher_callbacks *callbacks, otc_publisher_settings *settings)
otc_status	otc_publisher_delete (otc_publisher *publisher)
otc_stream *	otc_publisher_get_stream (otc_publisher *publisher)
otc_status	otc_publisher_set_publish_video (otc_publisher *publisher, otc_bool publish_video)
otc_status	otc_publisher_set_publish_audio (otc_publisher *publisher, otc_bool publish_audio)
otc_status	otc_publisher_set_publish_captions (otc_publisher *publisher, otc_bool publish_captions)
otc_bool	otc_publisher_get_publish_video (const otc_publisher *publisher)
otc_bool	otc_publisher_get_publish_audio (const otc_publisher *publisher)
otc_bool	otc_publisher_get_publish_captions (const otc_publisher *publisher)
otc_session *	otc_publisher_get_session (const otc_publisher *publisher)
otc_status	otc_publisher_set_max_audio_bitrate (otc_publisher *publisher, uint32_t bitrate)
otc_status	otc_publisher_set_rtc_stats_report_cb (otc_publisher *publisher, const struct otc_publisher_rtc_stats_report_cb cb)
otc_status	otc_publisher_get_rtc_stats_report (const otc_publisher *publisher)
otc_status	otc_publisher_set_audio_fallback_enabled (otc_publisher *publisher, otc_bool enabled)
otc_bool	otc_publisher_get_audio_fallback_enabled (const otc_publisher *publisher)
const char *	otc_publisher_get_publisher_id (const otc_publisher *publisher)
otc_status	otc_publisher_set_video_type (struct otc_publisher *publisher, enum otc_publisher_video_type video_type)
enum otc_publisher_video_type	otc_publisher_get_video_type (const struct otc_publisher *publisher)
void *	otc_publisher_get_user_data (const struct otc_publisher *publisher)
const char *	otc_publisher_get_name (const struct otc_publisher *publisher)
otc_status	otc_publisher_set_video_transformers (otc_publisher *publisher, otc_video_transformer **transformers, uint8_t size)
	Sets an array of video transformers to this publisher's video stream. If null resets transformers. More...
otc_status	otc_publisher_set_audio_transformers (otc_publisher *publisher, otc_audio_transformer **transformers, uint8_t size)
	Sets an array of audio transformers to this publisher's audio stream. If null resets transformers. More...
otc_status	otc_publisher_settings_set_subscriber_audio_fallback_enabled (otc_publisher_settings *settings, const otc_bool enabled)
otc_status	otc_publisher_settings_set_publisher_audio_fallback_enabled (otc_publisher_settings *settings, const otc_bool enabled)

Detailed Description

OpenTok Publisher.

This file includes the type definition for an OpenTok publisher along with several function declarations.

Typedef Documentation

otc_publisher

typedef struct otc_publisher otc_publisher

OpenTok publisher type definition.

A type representing a publisher of an audio-video stream to an OpenTok session.

otc_publisher_settings

typedef struct otc_publisher_settings otc_publisher_settings

OpenTok publisher settings type definition.

Enumeration Type Documentation

otc_publisher_error_code

enum otc_publisher_error_code

Error code enumeration for OpenTok publishers.

This enumeration represents several error codes associated with a publisher.

Enumerator
OTC_PUBLISHER_INTERNAL_ERROR	Internal error.
OTC_PUBLISHER_SESSION_DISCONNECTED	Error attempting to start captions in a session that you are not connected to.
OTC_PUBLISHER_TIMED_OUT	Time-out attempting to publish.
OTC_PUBLISHER_UNABLE_TO_PUBLISH	Unable to publish error.
OTC_PUBLISHER_WEBRTC_ERROR	WebRTC error.
OTC_PUBLISHER_ENCRYPTION_INTERNAL_ERROR	Internal error while encrypting a packet

otc_publisher_video_type

enum otc_publisher_video_type

Publisher video type enumeration.

This enumeration represents the different video types supported.

Enumerator
OTC_PUBLISHER_VIDEO_TYPE_CAMERA	Camera video stream.
OTC_PUBLISHER_VIDEO_TYPE_SCREEN	Screen capture video stream.

Function Documentation

otc_publisher_delete()

otc_status otc_publisher_delete

(

otc_publisher *

publisher

)

Releases a publisher instance, including all hardware resources bound to it.

Parameters

publisher

The publisher instance to be deleted.

Returns

Return value indicating either error or success.

otc_publisher_get_audio_fallback_enabled()

otc_bool otc_publisher_get_audio_fallback_enabled

(

const otc_publisher *

publisher

)

Returns whether the publisher audio-fallback feature is enabled or not. See the otc_publisher_set_audio_fallback_enabled function.

This function is deprecated.

Parameters

publisher

The publisher instance.

Returns

Whether the publisher audio-fallback feature is enabled or not.

otc_publisher_get_name()

const char* otc_publisher_get_name

(

const struct otc_publisher *

publisher

)

Gets the name for a given publisher.

Parameters

publisher

The publisher instance.

Returns

The name.

otc_publisher_get_publish_audio()

otc_bool otc_publisher_get_publish_audio

(

const otc_publisher *

publisher

)

Returns whether the Publisher is publishing audio or not.

Parameters

publisher

The publisher instance.

Returns

Whether the publisher is publishing audio or not.

otc_publisher_get_publish_captions()

otc_bool otc_publisher_get_publish_captions

(

const otc_publisher *

publisher

)

Returns whether the Publisher has captions active.

Parameters

publisher

The publisher instance.

Returns

Whether the publisher has captions active or not.

otc_publisher_get_publish_video()

otc_bool otc_publisher_get_publish_video

(

const otc_publisher *

publisher

)

Returns whether the publisher is publishing video or not.

Parameters

publisher

The publisher instance.

Returns

Whether the publisher is publishing video or not.

otc_publisher_get_publisher_id()

const char* otc_publisher_get_publisher_id

(

const otc_publisher *

publisher

)

Gets a unique identifier for a publisher.

Parameters

publisher

The publisher instance.

Returns

A unique identifier for the publisher. If there is an error, this is null.

otc_publisher_get_rtc_stats_report()

otc_status otc_publisher_get_rtc_stats_report

(

const otc_publisher *

publisher

)

Gets the RTC stats report for the subscriber. This is an asynchronous operation. create an otc_publisher_rtc_stats_report_cb struct and pass it into the otc_publisher_set_rtc_stats_report_cb function prior to calling this function. When the stats are available, the otc_publisher_set_rtc_stats_report_cb callback function is called.

Also see otc_publisher_callbacks.on_audio_stats, otc_publisher_callbacks.on_video_stats, and otc_subscriber_get_rtc_stats_report.

Parameters

publisher

The publisher.

otc_publisher_get_session()

otc_session* otc_publisher_get_session

(

const otc_publisher *

publisher

)

Returns the otc_session associated this publisher instance.

Parameters

publisher

The publisher instance.

Returns

The otc_session associated this instance. If there is an error, this is null.

otc_publisher_get_stream()

otc_stream* otc_publisher_get_stream

(

otc_publisher *

publisher

)

Returns the stream associated with the publisher.

Parameters

publisher

The publisher instance to get the stream from.

Returns

The stream associated with the publisher. If there is an error, this is null.

otc_publisher_get_user_data()

void* otc_publisher_get_user_data

(

const struct otc_publisher *

publisher

)

Gets user data for a given publisher.

Parameters

publisher

The publisher instance.

Returns

A pointer to the user data in memory.

otc_publisher_get_video_type()

enum otc_publisher_video_type otc_publisher_get_video_type

(

const struct otc_publisher *

publisher

)

Gets the publisher video type. See the otc_publisher_set_video_type function.

Parameters

publisher

The publisher instance.

Returns

The publisher video type.

otc_publisher_new()

otc_publisher* otc_publisher_new	(	const char *	name,
		const struct otc_video_capturer_callbacks *	capturer,
		const struct otc_publisher_callbacks *	callbacks
	)

Creates a new otc_publisher instance.

Parameters

name	The name of the publisher. Other clients can get the names for streams in the session.
capturer	Use this parameter if you want to provide a custom video capturer. If it is set to null, the publisher uses a default video capturer using the system's camera.
callbacks	A pointer to the structure with the publisher callback function pointers.

Returns

A new otc_publisher instance. If there is an error, this is null.

otc_publisher_new_with_settings()

otc_publisher* otc_publisher_new_with_settings	(	const struct otc_publisher_callbacks *	callbacks,
		otc_publisher_settings *	settings
	)

Creates a new otc_publisher instance.

Parameters

callbacks	A pointer to the struct with publisher callback function pointers.
settings	The settings struct containing the desired settings for the publisher.

Returns

A new otc_publisher instance. If there is an error, this is null.

otc_publisher_set_audio_fallback_enabled()

otc_status otc_publisher_set_audio_fallback_enabled	(	otc_publisher *	publisher,
		otc_bool	enabled
	)

Enables or disables the subscriber audio-fallback feature.

The audio-fallback feature is available in sessions that use the OpenTok Media Router. With the audio-fallback feature enabled (the default), when the OpenTok Media Router determines that a stream's quality has degraded significantly for a specific subscriber to the stream, it disables the video in that subscriber in order to preserve audio quality.

To turn off the audio-fallback feature, call the otc_publisher_set_audio_fallback_enabled function (and pass in OTC_FALSE) before calling the otc_session_publish function.

This function is deprecated. See otc_publisher_settings_set_subscriber_audio_fallback_enabled.

Parameters

publisher	The publisher to be affected.
enabled	Whether we want to enable the audio-fallback feature or not.

Returns

Return value indicating either error or success.

otc_publisher_set_audio_transformers()

otc_status otc_publisher_set_audio_transformers	(	otc_publisher *	publisher,
		otc_audio_transformer **	transformers,
		uint8_t	size
	)

Sets an array of audio transformers to this publisher's audio stream. If null resets transformers.

The array can be composed by vonage audio transformers provided by ml-library and/or custom transfomers. Transformers contain a pointer to callback invoked on each audio frame.

Note: This function only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Parameters

[in]	publisher	The publisher instance.
[in]	transformers	Array of opaque pointers otc_audio_transformer in the order to be applied to the stream.
[in]	size	size of the array.

Returns

an error in the event of an error otherwise OTC_SUCCESS.

otc_publisher_set_max_audio_bitrate()

otc_status otc_publisher_set_max_audio_bitrate	(	otc_publisher *	publisher,
		uint32_t	bitrate
	)

Sets the max audio bitrate for the publisher.

Parameters

publisher	The publisher to be affected.
bitrate	The desired bitrate.

Returns

Return value indicating either error or success.

otc_publisher_set_publish_audio()

otc_status otc_publisher_set_publish_audio	(	otc_publisher *	publisher,
		otc_bool	publish_audio
	)

Whether to publish audio or not. By default, streams publish both audio and video.

Parameters

publisher	The publisher to be affected.
publish_audio	Whether to publish audio or not.

Returns

Return value indicating either error or success.

otc_publisher_set_publish_captions()

otc_status otc_publisher_set_publish_captions	(	otc_publisher *	publisher,
		otc_bool	publish_captions
	)

Whether to make captions active or not. By default, it is off.

Parameters

publisher	The publisher to be affected.
publish_captions	Whether to enable captioning or not.

Returns

Return value indicating either error or success.

otc_publisher_set_publish_video()

otc_status otc_publisher_set_publish_video	(	otc_publisher *	publisher,
		otc_bool	publish_video
	)

Whether to publish video or not. By default, streams publish both audio and video.

Parameters

publisher	The publisher to be affected.
publish_video	Whether to publish video or not.

Returns

Return value indicating either error or success.

otc_publisher_set_rtc_stats_report_cb()

otc_status otc_publisher_set_rtc_stats_report_cb	(	otc_publisher *	publisher,
		const struct otc_publisher_rtc_stats_report_cb	cb
	)

Sets the RTC stats report callback the publisher.

Parameters

publisher	The publisher instance.
cb	The otc_publisher_rtc_stats_report_cb struct that includes the callback function for the RTC stats report.

See also

otc_publisher_get_rtc_stats_report.

otc_publisher_set_video_transformers()

otc_status otc_publisher_set_video_transformers	(	otc_publisher *	publisher,
		otc_video_transformer **	transformers,
		uint8_t	size
	)

Sets an array of video transformers to this publisher's video stream. If null resets transformers.

The array can be composed by vonage video transformers provided by ml-library and/or custom transfomers. Transformers contain a pointer to callback invoked on each video frame.

Note: This function only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Parameters

[in]	publisher	The publisher instance.
[in]	transformers	Array of opaque pointers otc_video_transformer in the order to be applied to the stream.
[in]	size	size of the array.

Returns

an error in the event of an error otherwise OTC_SUCCESS.

otc_publisher_set_video_type()

otc_status otc_publisher_set_video_type	(	struct otc_publisher *	publisher,
		enum otc_publisher_video_type	video_type
	)

Sets the publisher video type. By default, videos have the video type set to OTC_PUBLISHER_VIDEO_TYPE_CAMERA (indicating the source of the video is a camera). Set this to OTC_PUBLISHER_VIDEO_TYPE_SCREEN to indicate that the video source is screen sharing. Other clients can detect the video type for streams in the session (to determine the video source type).

Parameters

publisher	The publisher to be affected.
video_type	The video type for the publisher.

Returns

Return value indicating either error or success.

otc_publisher_settings_delete()

otc_status otc_publisher_settings_delete

(

otc_publisher_settings *

settings

)

Deletes an otc_publisher_settings instance.

Parameters

settings

The otc_publisher_settings instance to be deleted.

Returns

Return value indicating either error or success.

otc_publisher_settings_new()

otc_publisher_settings* otc_publisher_settings_new

(

)

Creates a new otc_publisher_settings instance.

Returns

A new otc_publisher_settings instance

otc_publisher_settings_set_audio_track()

otc_status otc_publisher_settings_set_audio_track	(	otc_publisher_settings *	settings,
		otc_bool	enabled
	)

Enables an audio track for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable the existence of an audio track for a publisher to be constructed with otc_publisher_new_with_settings.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_auto_gain_control()

otc_status otc_publisher_settings_set_auto_gain_control	(	otc_publisher_settings *	settings,
		otc_bool	enabled
	)

Enables audio automatic gain control for a publisher to be constructed with otc_publisher_new_with_settings.

It does not work in the Vonage Video API Linux SDK.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true, the default) or disable (false) automatic gain control.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_default_camera_capture_resolution()

otc_status otc_publisher_settings_set_default_camera_capture_resolution	(	otc_publisher_settings *	settings,
		const enum otc_camera_capture_resolution	camera_capture_resolution
	)

Sets a camera capture resolution for default video capturers.

Custom video capturers should not honor the capturing resolution set by otc_publisher_settings_set_default_camera_capture_resolution, the use of this is only for default video capturers.

Parameters

camera_capture_resolution	The camera capture resolution for default video capturers.
settings	The otc_publisher_settings instance to be affected.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_disable_audio_processing()

otc_status otc_publisher_settings_set_disable_audio_processing	(	otc_publisher_settings *	settings,
		otc_bool	disabled
	)

When otc_publisher_settings_set_disable_audio_processing is set to true, the individual settings for acoustic echo cancellation, automatic gain control, and noise-suppression will be ignored and audio will not be processed at all. The default value is false. See otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true) or disable (false, the default) audio processing support.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_echo_cancellation()

otc_status otc_publisher_settings_set_echo_cancellation	(	otc_publisher_settings *	settings,
		otc_bool	enabled
	)

Enables acoustic echo cancellation for a publisher to be constructed with otc_publisher_new_with_settings.

Note: This function only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true, the default) or disable (false) acoustic echo cancellation support.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_name()

otc_status otc_publisher_settings_set_name	(	otc_publisher_settings *	settings,
		const char *	name
	)

Sets the desired name for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
name	The name for the publisher. Other clients can get the names for streams in the session.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_noise_suppression()

otc_status otc_publisher_settings_set_noise_suppression	(	otc_publisher_settings *	settings,
		otc_bool	enabled
	)

Enables noise suppression for a publisher to be constructed with otc_publisher_new_with_settings.

Note: This function only applies to the Vonage Video API macOS SDK. It does not work in the Vonage Video API Linux SDK.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true, the default) or disable (false) noise suppression.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_opus_dtx()

otc_status otc_publisher_settings_set_opus_dtx	(	otc_publisher_settings *	settings,
		otc_bool	enabled
	)

Enables Opus DTX for a publisher to be constructed with otc_publisher_new_with_settings. Enabling Opus DTX can reduce bandwidth usage in streams that have long periods of silence.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Whether to enable (true) or disable (false, the default) Opus DTX support.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_publisher_audio_fallback_enabled()

otc_status otc_publisher_settings_set_publisher_audio_fallback_enabled	(	otc_publisher_settings *	settings,
		const otc_bool	enabled
	)

Enables or disables the publisher audio-fallback feature.

With the publisher audio-fallback feature enabled, when the Publisher determines that a stream's quality has degraded significantly, it disables the video stream in order to preserve audio quality and continues to send the audio stream. The capturer corresponding to this publisher will not be disabled, and the captured frames will still be seen on the publisher side.

The default setting is OTC_FALSE (the audio-fallback feature is disabled). When using the screen video type in a session that uses the OpenTok Media Server, the publisher audio-fallback setting is set to OTC_FALSE by default, so that the video does not drop out in subscribers.

Parameters

settings	The publisher settings to be affected.
enabled	Whether we want to enable the audio-fallback feature or not.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_scalable_screenshare()

otc_status otc_publisher_settings_set_scalable_screenshare	(	otc_publisher_settings *	settings,
		const otc_bool	enabled
	)

Allow use of scalable video scalable video for a publisher that has the otc_publisher_video_type set to OTC_PUBLISHER_VIDEO_TYPE_SCREEN with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable the use of scalable video for screen-sharing streams.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_stereo()

otc_status otc_publisher_settings_set_stereo	(	otc_publisher_settings *	settings,
		otc_bool	enabled
	)

Enables stereo audio for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable stereo audio support for a publisher to be constructed with otc_publisher_new_with_settings.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_subscriber_audio_fallback_enabled()

otc_status otc_publisher_settings_set_subscriber_audio_fallback_enabled	(	otc_publisher_settings *	settings,
		const otc_bool	enabled
	)

Enables or disables the subscriber audio-fallback feature (for subscribers to the published stream)

The subscriber audio-fallback feature is available in sessions that use the OpenTok Media Router. With the audio-fallback feature enabled (the default), when the OpenTok Media Router determines that a stream's quality has degraded significantly for a specific subscriber to the stream, it disables the video in that subscriber in order to preserve audio quality.

The default setting is OTC_TRUE (the audio-fallback feature is enabled). When using the screen video type, the subscriber audio-fallback setting is set to OTC_FALSE by default, so that the video does not drop out in subscribers.

Parameters

settings	The publisher settings to be affected.
enabled	Whether we want to enable the audio-fallback feature or not.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_video_capturer()

otc_status otc_publisher_settings_set_video_capturer	(	otc_publisher_settings *	settings,
		const struct otc_video_capturer_callbacks *	capturer
	)

Sets the video capturer for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
capturer	The video capturer.

Returns

Return value indicating either error or success.

otc_publisher_settings_set_video_track()

otc_status otc_publisher_settings_set_video_track	(	otc_publisher_settings *	settings,
		otc_bool	enabled
	)

Enables a video track for a publisher to be constructed with otc_publisher_new_with_settings.

Parameters

settings	The otc_publisher_settings instance to be affected.
enabled	Enable/disable the existence of an video track for a publisher to be constructed with otc_publisher_new_with_settings.

Returns

Return value indicating either error or success.