Image Management And Configuration [OPENAPI_IMAGE]

Macros
#define	OPEN_IMAGE_NAME_NONE   "none"

Functions
open_error_t	openapiBootCodeUpdate (openapiClientHandle_t *client_handle, uint32_t unit)
	Updates the bootcode from the currently activated image.
open_error_t	openapiImageActivate (openapiClientHandle_t *client_handle, uint32_t unit, open_buffdesc *imageLabel, OPEN_BOOL_t updateBootCode)
	Sets the specified image as the active image for the subsequent re-boots.
open_error_t	openapiImageDelete (openapiClientHandle_t *client_handle, uint32_t unit, open_buffdesc *imageLabel)
	Deletes the specified image.
open_error_t	openapiImageDescrGet (openapiClientHandle_t *client_handle, open_buffdesc *imageLabel, open_buffdesc *imageDescr)
	Get the text description for a given image.
open_error_t	openapiImageDescrSet (openapiClientHandle_t *client_handle, open_buffdesc *imageLabel, open_buffdesc *imageDescr)
	Set the text description for a given image.
open_error_t	openapiImageLabelIsValid (openapiClientHandle_t *client_handle, open_buffdesc *imageLabel, OPEN_BOOL_t *isValid)
	Determines if the image label refers to a valid image name.
open_error_t	openapiImageLabelsGet (openapiClientHandle_t *client_handle, open_buffdesc *activeLabel, open_buffdesc *backupLabel)
	Get the label names for both active and backup images.
open_error_t	openapiImageNamesGet (openapiClientHandle_t *client_handle, uint32_t unit, open_buffdesc *activeImage, open_buffdesc *backupImage, open_buffdesc *activatedImage)
	Get the image names for both active, backup, and activated.
open_error_t	openapiImageUpgrade (openapiClientHandle_t *client_handle, open_buffdesc *imagePath, open_buffdesc *imageLabel)
	Get a locally copied image path, perform validation on it and on success, upgrade the switch with this image.

Detailed Description

Function Documentation

open_error_t openapiBootCodeUpdate	(	openapiClientHandle_t *	client_handle,
		uint32_t	unit
	)

Updates the bootcode from the currently activated image.

Parameters

[in]	client_handle	Client handle from registration API.
[in]	unit	Unit number
	-	Minimum value 1
	-	Maximum value openapiUnitMgrUnitMaxGet()

Return values

OPEN_E_NONE	if validation is successful.
OPEN_E_PARAM	if parameters is not defined correctly.
OPEN_E_UNAVAIL	Not supported for this platform.

Note

This API is valid for the management unit in a stacking build.

OpEN API Version: 1.8

Examples:

image_example.c.

open_error_t openapiImageActivate	(	openapiClientHandle_t *	client_handle,
		uint32_t	unit,
		open_buffdesc *	imageLabel,
		OPEN_BOOL_t	updateBootCode
	)

Sets the specified image as the active image for the subsequent re-boots.

Parameters

[in]	client_handle	Client handle from registration API.
[in]	unit	Unit number
	-	Minimum value 1
	-	Maximum value openapiUnitMgrUnitMaxGet()
[in]	imageLabel	Image label name
	-	Minimum length 1
	-	Maximum length OPENAPI_IMAGE_NAME_MAX
[in]	updateBootCode	OPEN_TRUE to activate, else OPEN_FALSE

Return values

OPEN_E_NONE	if text set successful.
OPEN_E_FAIL	if text set failed.
OPEN_E_PARAM	if parameters is not defined correctly.
OPEN_E_NOT_FOUND	if image not found.
OPEN_E_UNAVAIL	if the specified image is not the backup image
OPEN_E_EXISTS	if the image is already activated

OpEN API Version: 1.8

Examples:

image_example.c.

open_error_t openapiImageDelete	(	openapiClientHandle_t *	client_handle,
		uint32_t	unit,
		open_buffdesc *	imageLabel
	)

Deletes the specified image.

Parameters

[in]	client_handle	Client handle from registration API.
[in]	unit	Unit number
	-	Minimum value 1
	-	Maximum value openapiUnitMgrUnitMaxGet()
[in]	imageLabel	Image label name
	-	Minimum length 1
	-	Maximum length OPENAPI_IMAGE_NAME_MAX

Return values

OPEN_E_NONE	if text set successful.
OPEN_E_FAIL	if text set failed.
OPEN_E_PARAM	if parameters is not defined correctly.
OPEN_E_NOT_FOUND	if image not found.
OPEN_E_UNAVAIL	if the specified image is active/activated.

Note

The current active image is never deleted.

The activated backup image is never deleted.

Some products with dual image capability permit the user to delete the backup image only.

OpEN API Version: 1.8

Examples:

image_example.c.

open_error_t openapiImageDescrGet	(	openapiClientHandle_t *	client_handle,
		open_buffdesc *	imageLabel,
		open_buffdesc *	imageDescr
	)

Get the text description for a given image.

Parameters

[in]	client_handle	Client handle from registration API
[in]	imageLabel	Image label name
	-	Buffer size should be OPENAPI_IMAGE_NAME_MAX
[out]	imageDescr	Associated text
	-	Buffer size should be OPENAPI_DEFAULT_IMAGE_DESCR_MAX

Return values

OPEN_E_NONE	if text get successful.
OPEN_E_FAIL	if text get failed.
OPEN_E_PARAM	if parameters is not defined correctly.
OPEN_E_NOT_FOUND	if image not found.

OpEN API Version: 1.8

Examples:

image_example.c.

open_error_t openapiImageDescrSet	(	openapiClientHandle_t *	client_handle,
		open_buffdesc *	imageLabel,
		open_buffdesc *	imageDescr
	)

Set the text description for a given image.

Parameters

[in]	client_handle	Client handle from registration API
[in]	imageLabel	Image label name
	-	Minimum length 1
	-	Maximum length OPENAPI_IMAGE_NAME_MAX
[in]	imageDescr	Associated text
	-	Minimum length 1
	-	Maximum length OPENAPI_DEFAULT_IMAGE_DESCR_MAX

Return values

OPEN_E_NONE	if text set successful.
OPEN_E_FAIL	if text set failed.
OPEN_E_PARAM	if parameters is not defined correctly.
OPEN_E_NOT_FOUND	if image not found.
OPEN_E_UNAVAIL	The image is currently in-use.

OpEN API Version: 1.8

Examples:

image_example.c.

open_error_t openapiImageLabelIsValid	(	openapiClientHandle_t *	client_handle,
		open_buffdesc *	imageLabel,
		OPEN_BOOL_t *	isValid
	)

Determines if the image label refers to a valid image name.

Parameters

[in]	client_handle	Client handle from registration API.
[in]	imageLabel	Image label name
	-	Minimum length 1
	-	Maximum length OPENAPI_IMAGE_NAME_MAX
[out]	isValid	Returns OPEN_TRUE if image label is valid, else OPEN_FALSE if not

Return values

OPEN_E_NONE	validation was successful. isValid contains a legitimate value only in this case.
OPEN_E_FAIL	validation failed.
OPEN_E_PARAM	parameters were not defined correctly.

Note

This API expects the identifying string (label) used to refer to each code image file residing in non-volatile memory on the switch, such as "active" and "backup". It is not the actual name of a specific image (e.g. "8.2.0.1").

This function doesn't test validity of the label itself, but the validity of what the label refers to. In some cases, what this function expects to be passed in is either "active" or "backup", while on some platforms, a valid label might be "image1" or "image2". openapiImageLabelsGet can be used to obtain these label names.

A deleted image (e.g., via openapiImageDelete) will be reported as invalid by this function, because what the corresponding label (e.g., "backup") refers to is not present or available.

OpEN API Version: 1.8

Examples:

image_example.c.

open_error_t openapiImageLabelsGet	(	openapiClientHandle_t *	client_handle,
		open_buffdesc *	activeLabel,
		open_buffdesc *	backupLabel
	)

Get the label names for both active and backup images.

Parameters

[in]	client_handle	Client handle from registration API
[out]	activeLabel	Active label name
[out]	backupLabel	Backup label name

Return values

OPEN_E_NONE	if label get successful.
OPEN_E_FAIL	if label get failed.
OPEN_E_PARAM	if parameters is not defined correctly.

Note

This API provides the identifying string (label) used to refer to each code image file residing in non-volatile memory on the switch, such as "active" and "backup". It is not the actual name of a specific image (e.g. "8.2.0.1").

Buffer size for image labels should be OPENAPI_IMAGE_NAME_MAX.

OpEN API Version: 1.8

Examples:

image_example.c.

open_error_t openapiImageNamesGet	(	openapiClientHandle_t *	client_handle,
		uint32_t	unit,
		open_buffdesc *	activeImage,
		open_buffdesc *	backupImage,
		open_buffdesc *	activatedImage
	)

Get the image names for both active, backup, and activated.

Parameters

[in]	client_handle	Client handle from registration API.
[in]	unit	Unit number
	-	Minimum value 1
	-	Maximum value openapiUnitMgrUnitMaxGet()
[out]	activeImage	Active image name
[out]	backupImage	Backup image name
[out]	activatedImage	Activated image name

Return values

OPEN_E_NONE	if name get successful.
OPEN_E_FAIL	if name get failed.
OPEN_E_PARAM	if parameters is not defined correctly.

Note

This API provides the names of the code image files residing in non-volatile memory on the switch (e.g. "8.2.1.1").

Buffer size for image names should be OPENAPI_IMAGE_NAME_MAX.

An image name of OPEN_IMAGE_NAME_NONE indicates the image is not present on the device.

OpEN API Version: 1.8

Examples:

image_example.c.

open_error_t openapiImageUpgrade	(	openapiClientHandle_t *	client_handle,
		open_buffdesc *	imagePath,
		open_buffdesc *	imageLabel
	)

Get a locally copied image path, perform validation on it and on success, upgrade the switch with this image.

Parameters

[in]	client_handle	Client handle from registration API.
[in]	imagePath	Complete path for the image in Linux
[in]	imageLabel	Active or Backup image label

Return values

OPEN_E_NONE	if image validation and upgrade are successful.
OPEN_E_FAIL	if image validation or upgrade fails.
OPEN_E_PARAM	if parameters is not defined correctly.
OPEN_E_UNAVAIL	if platform does not support function.

Note

This API validates a locally downloaded image. If successful, the switch image identified by the imageLabel is updated.

This API expects the imageLabel parameter to contain the identifying string (label) used to refer to each code image file residing in non-volatile memory on the switch, such as "active" and "backup". It is not the actual name of a specific image (e.g. "8.2.0.1").

Buffer size for imagePath and imageLabel should be OPENAPI_IMAGE_NAME_MAX.

OpEN API Version: 1.14

Examples:

image_example.c.