Alerts

Sending alerts. More...

Typedefs
typedef struct roc_alerter_type *	roc_alerter
	Handle to a private roc_alerter type.

Functions
roc_error	roc_initialize_alerter (roc_alerter *alerter, const char *key_file_path)
	Create a roc_alerter object. More...
roc_error	roc_alerter_has_sms_credentials (const roc_alerter alerter, bool *has_sms_credentials)
	Determine whether or not a roc_alerter can send SMS/MMS alerts. More...
roc_error	roc_alerter_has_email_credentials (const roc_alerter alerter, bool *has_email_credentials)
	Determine whether or not a roc_alerter can send email alerts. More...
roc_error	roc_alerter_has_whatsapp_credentials (const roc_alerter alerter, bool *has_whatsapp_credentials)
	Determine whether or not a roc_alerter can send WhatsApp alerts. More...
roc_error	roc_send_text_message (const roc_alerter alerter, const char *phone_number, const char *message, roc_buffer image_data, size_t image_data_length)
	Send a text message alert. More...
roc_error	roc_send_whatsapp_message (const roc_alerter alerter, const char *phone_number, const char *alerts_sender_name, const char *person_name, const char *camera_name, const char *date_time, roc_buffer image_data, size_t image_data_length)
	Send a WhatsApp message alert. More...
roc_error	roc_send_email (const roc_alerter alerter, const char *to_email_address, const char *recipient_name, const char *subject, const char *message, roc_buffer image_data, size_t image_data_length)
	Send an email alert. More...
roc_error	roc_free_alerter (roc_alerter *alerter)
	Free a roc_alerter object. More...

Detailed Description

Sending alerts.

Send a text message alert with roc_send_text_message, a WhatsApp message with roc_send_whatsapp_message, or an email alert with roc_send_email. roc_alerter objects must be initialized with a key file, supplied by Rank One. This key file is specific to each user (whether company or individual) of ROC Alerts, and must not be modified. Tokens contained within the key file authenticate ROC API alert requests. Check if your key file has credentials for particular alert methods via roc_alerter_has_sms_credentials, roc_alerter_has_email_credentials, and roc_alerter_has_whatsapp_credentials.

Function Documentation

roc_initialize_alerter()

roc_error roc_initialize_alerter	(	roc_alerter *	alerter,
		const char *	key_file_path
	)

Create a roc_alerter object.

Initialize a roc_alerter with the path to your Rank One-supplied key file. The key file will be used to authenticate roc_send_text_message, and roc_send_email, and roc_send_whatsapp_message requests.

Example

roc_alerter alerter;
roc_initialize_alerter(&alerter, "C:\\local\\rocAlertsKeyFile.txt");

Parameters

[in]	alerter	roc_alerter to initialize.
[in]	key_file_path	Path to key file.

Remarks

This function is reentrant.

roc_alerter_has_sms_credentials()

roc_error roc_alerter_has_sms_credentials	(	const roc_alerter	alerter,
		bool *	has_sms_credentials
	)

Determine whether or not a roc_alerter can send SMS/MMS alerts.

Check whether the roc_alerter has access to send SMS and MMS messages, based on the credentials found in the key file passed to roc_initialize_alerter.

Example

roc_alerter alerter;
roc_ensure(roc_initialize_alerter(&alerter, "C:\\local\\rocAlertsKeyFile.txt"));
bool textMessagesEnabled;
roc_ensure(roc_alerter_has_sms_credentials(alerter, &textMessagesEnabled));

Parameters

[in]	alerter	Alerter to check credentials for.
[out]	has_sms_credentials	Status of whether or not SMS/MMS is enabled.

Remarks

This function is thread-safe.

roc_alerter_has_email_credentials()

roc_error roc_alerter_has_email_credentials	(	const roc_alerter	alerter,
		bool *	has_email_credentials
	)

Determine whether or not a roc_alerter can send email alerts.

Check whether the roc_alerter has access to send emails based, on the credentials found in the key file passed to roc_initialize_alerter.

Parameters

[in]	alerter	Alerter to check credentials for.
[out]	has_email_credentials	Status of whether or not email is enabled.

Remarks

This function is thread-safe.

roc_alerter_has_whatsapp_credentials()

roc_error roc_alerter_has_whatsapp_credentials	(	const roc_alerter	alerter,
		bool *	has_whatsapp_credentials
	)

Determine whether or not a roc_alerter can send WhatsApp alerts.

Check whether the roc_alerter has access to send WhatsApp messages based, on the credentials found in the key file passed to roc_initialize_alerter.

Parameters

[in]	alerter	Alerter to check credentials for.
[out]	has_whatsapp_credentials	Status of whether or not WhatsApp is enabled.

Remarks

This function is thread-safe.

roc_send_text_message()

roc_error roc_send_text_message	(	const roc_alerter	alerter,
		const char *	phone_number,
		const char *	message,
		roc_buffer	image_data,
		size_t	image_data_length
	)

Send a text message alert.

Send an SMS message or MMS message by supplying an optional image parameter. Outside of the United States and Canada, MMS messages will automatically be converted to SMS, and will have a link to the image embedded in the SMS text contents.

Example

roc_alerter alerter;
roc_ensure(roc_initialize_alerter(&alerter, "C:\\local\\myKeyFile.txt"));
roc_image image;
roc_ensure(roc_read_image("C:\\Pictures\\myPicture.jpg", ROC_BGR24, &image));
roc_buffer buffer;
size_t bufferSize;
roc_ensure(roc_encode_image(image, ".jpg", 100, &buffer, &bufferSize));
roc_ensure(roc_send_text_message(alerter, "12568051806", "Receiving ROC Alert!", buffer, bufferSize));
// Clean up resources...
roc_ensure(roc_free_alerter(&alerter));
roc_ensure(roc_free_image(image));
roc_ensure(roc_free_buffer(&buffer));

Parameters

[in]	alerter	roc_alerter to handle sending alert.
[in]	phone_number	Text message destination. Requires country code.
[in]	message	Text message contents. 1600 character limit. Messages longer than 160 characters will be segmented.
[in]	image_data	Optional image data parameter to be passed as a roc_buffer. Must be the output of roc_encode_image. Alert will automatically convert to MMS. Setting to null results in no image being sent.
[in]	image_data_length	Length of the optional image data. Setting to zero results in no image being sent.

Remarks

This function is reentrant.

roc_send_whatsapp_message()

roc_error roc_send_whatsapp_message	(	const roc_alerter	alerter,
		const char *	phone_number,
		const char *	alerts_sender_name,
		const char *	person_name,
		const char *	camera_name,
		const char *	date_time,
		roc_buffer	image_data,
		size_t	image_data_length
	)

Send a WhatsApp message alert.

Send a WhatsApp alert message with an optional image parameter. The WhatsApp API requires messages send to match the template format:

Alert from {{1}}: {{2}} was seen by camera {{3}} at time {{4}}. Click {{5}} to view image.

where the fifth argument, image link, is optional. WhatsApp messages not matching this template format may be rejected by the WhatsApp API. Therefore, it is important to keep arguments supplied to roc_send_whatsapp_message as short as possible. For example, instead of setting the alert sender name to "Rank One Computing Corporation", consider setting it to "Rank One Computing".

Example

roc_alerter alerter;
roc_ensure(roc_initialize_alerter(&alerter, "C:\\local\\myKeyFile.txt"));
roc_image image;
roc_ensure(roc_read_image("C:\\Pictures\\myPicture.jpg", ROC_BGR24, &image));
roc_buffer buffer;
size_t bufferSize;
roc_ensure(roc_encode_image(image, ".jpg", 100, &buffer, &bufferSize));
roc_ensure(roc_send_whatsapp_message(alerter, "12568051806", "Rank One Computing", "Unknown Person", "AXIS Hallway Camera", "4:06 PM Sept 20, 2021", buffer, bufferSize));
// Clean up resources...
roc_ensure(roc_free_alerter(&alerter));
roc_ensure(roc_free_image(image));
roc_ensure(roc_free_buffer(&buffer));

Parameters

[in]	alerter	roc_alerter to handle sending alert.
[in]	phone_number	Text message destination. Requires country code.
[in]	alerts_sender_name	Name of organization generating the alert.
[in]	person_name	Name of the alert subject.
[in]	camera_name	Name of the camera generating the alert.
[in]	date_time	Date and time the alert was generated.
[in]	image_data	Optional image data parameter to be passed as a roc_buffer. Must be the output of roc_encode_image. Alert will automatically convert to MMS. Setting to null results in no image being sent.
[in]	image_data_length	Length of the optional image data. Setting to zero results in no image being sent.

Remarks

This function is reentrant.

roc_send_email()

roc_error roc_send_email	(	const roc_alerter	alerter,
		const char *	to_email_address,
		const char *	recipient_name,
		const char *	subject,
		const char *	message,
		roc_buffer	image_data,
		size_t	image_data_length
	)

Send an email alert.

Send an email with an optional image parameter. Alert emails contain sender "alert@rankone.io" with reply-to "noreply@rankone.io". However, sender and reply-to can be changed by contacting Rank One for a modififed key file. Total email size including headers and content should not exceed 20MB.

Example

roc_alerter alerter;
roc_ensure(roc_initialize_alerter(&alerter, "C:\\local\\myKeyFile.txt"));
roc_image image;
roc_ensure(roc_read_image("C:\\Pictures\\myPicture.jpg", ROC_BGR24, &image));
roc_buffer buffer;
size_t bufferSize;
roc_ensure(roc_encode_image(image, ".jpg", 100, &buffer, &bufferSize));
roc_ensure(roc_send_email(alerter, "example@gmail.com", "John Doe", "ROC Alert Subject", "Receiving ROC Alert!", buffer, bufferSize));
// Clean up resources...
roc_ensure(roc_free_alerter(&alerter));
roc_ensure(roc_free_image(image));
roc_ensure(roc_free_buffer(&buffer));

Parameters

[in]	alerter	roc_alerter to handle sending alert.
[in]	to_email_address	Destination email address.
[in]	recipient_name	Name of intended recipient. Will appear in email header.
[in]	subject	Email subject. Will appear in email header.
[in]	message	Email text contents.
[in]	image_data	Optional image data parameter to be passed as a roc_buffer. Must be the output of roc_encode_image. Alert will automatically convert to MMS. Setting to null results in no image being sent.
[in]	image_data_length	Length of the optional image data. Setting to zero results in no image being sent.

Remarks

This function is reentrant.

roc_free_alerter()

roc_error roc_free_alerter

(

roc_alerter *

alerter

)

Free a roc_alerter object.

Deallocate a roc_alerter object.

Example

roc_alerter alerter;
// Use alerter...
roc_free_alerter(&alerter);

Parameters

[in]

alerter

roc_alerter to free.

Remarks

This function is reentrant.