rf_location.h File Reference

Functions to assist with RIP farm location IDs. More...

#include <stdarg.h>

Functions
char *	rf_location_id (const char *format,...)
	Create a location ID suitable for use in raster descriptions and elsewhere. More...
char *	rf_vlocation_id (const char *format, va_list ap)
	Create a location ID suitable for use in raster descriptions and elsewhere. More...

Detailed Description

Functions to assist with RIP farm location IDs.

Copyright (C) 2023 Global Graphics Software Ltd. All rights reserved. Global Graphics Software Ltd. Confidential Information.

Function Documentation

rf_location_id()

char* rf_location_id	(	const char *	format,
			...
	)

Create a location ID suitable for use in raster descriptions and elsewhere.

Parameters

[in]

format

A format string used to determine what components to put in the location ID.

Returns

A zero-terminated string, or NULL if there was an error creating the string. The string must be freed using rf_mem_free() after use.

This function is conceptually similar to the printf() family of functions, but with a restricted set of valid format codes. It constructs an ID string according to a format, inserting components to represent different localities within the RIP farm.

As with printf(), literal characters are copied from the format string, and constructed components are inserted using format codes. Format codes are indicated in the format string using the % character. The set of valid format codes are:

%F

Insert a component representing this RIP farm (distinguished from any other RIP farm that may be running on the same network).

%B

Insert a component representing this Blade (i.e., machine or VM).

%P

Insert a component representing this process.

%s

Insert a user string. The next argument in the args list should be a char * pointer.

%d

Insert a signed user integer. The next argument in the args list should be an int.

%u

Insert an unsigned user integer. The next argument in the args list should be an int.

%x

Insert a hexadecimal user integer. The next argument in the args list should be an int.

%c

Insert a user character. The next argument in the args list should be an char (which will be promoted to int).

%

The character '%' itself.

If any other format escape not on this list is used, this function will return NULL. In particular, note that field width and precision specifications are not supported.

Location components created by this function use characters from the union of valid characters in a domain name and an IP address (IPv4 and IPv6), i.e., a-z A-Z 0-9 - _ : .

Location IDs are passed to the Raster Manager for use in routing decisions and placement decisions. The Raster Manager will only ever compare location IDs for equality, it will never attempt to deconstruct them. However, OEM components can parse and deconstruct locations known to have been created by other OEM components.

Errors may be caused by a NULL or empty format string, an invalid argument to a format, an invalid format code, memory exhaustion, or an internal error in a function used to find an ID component.

rf_vlocation_id()

char* rf_vlocation_id	(	const char *	format,
		va_list	ap
	)

Create a location ID suitable for use in raster descriptions and elsewhere.

Parameters

[in]	format	A format string used to determine what components to put in the location ID.
[in]	ap	A handle to a variable-length list of arguments, already initialised using va_start() on entry.

Returns

A zero-terminated string, or NULL if there was an error creating the string. The string must be freed using rf_mem_free() after use.

See the description of rf_location_id() for details of the format specifiers and output.