Table Of Contents

PAK Management Functions

asyncDownloadPAKInfo

createPAKs

deletePAKs

listAllFoldersByPAK

listAllPAKsInFolder

listPAKContainFeatures

readPAKs

writePAKs

PAK Management Functions

---

This chapter provides information about the following product authorization key (PAK) management functions:

•asyncDownloadPAKInfo

•createPAKs

•deletePAKs

•listAllFoldersByPAK

•listAllPAKsInFolder

•listPAKContainFeatures

•readPAKs

•writePAKs

asyncDownloadPAKInfo

Synopsis

String asyncDownloadPAKInfo(UserToken token, String[] pak_ids,IDStatusListener listener) 
throws RemoteException;

Description

This function downloads the information that is associated with the given PAK IDs from the Cisco Product License Registration Portal and stores the information in the inventory.

This function is nonblocking and returns a request ID to the caller immediately. When calling this function, the client program provides a listener object that implements the StatusListener interface. When the function is completed, the onStatus() method in the listener object is invoked.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
pak_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of PAK IDs that identify interested PAKs. A PAK ID is generated by using the createPAK function, passing a PAK name as a parameter to get the PAK ID.
listener	IDStatusListener object, mandatory	—	An object which implements IDStatusListener interface.

Return

This function returns a request ID to the caller. When the operation is complete, the status is provided as the input parameter of the onStatus() method. The listener received IDStatus upon operation complete. The IDStatus contains a list of IDStatusItem, which includes the PAK ID and the error code and error message of the operation in this PAK ID.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

The input parameter of the onStatus() method in IDStatusListener contains the error code and messages. More than one error code and message may be contained in the IDStatus object. The following example shows the error code and messages in the onStatus() method:

		public void onStatus(String request_id, IDStatus status) {

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			IDStatusItem[] items = status.getIDStatusItems()

			// Iterate through the list to get individual status.

			for (int i = 0; i < items.length(); i++) {

				// Get the individual object ID returned by the operation.

				String id = items[i].getID();

				// Get the individual error code corresponding to 

				// the object ID.

				int item_err_code = items[i].getErrorCode();

				// Get the individual error message corresponding to 

				// the object ID.

				String item_err_msg = items[i].getErrorMessage();

			}

		}

createPAKs

Synopsis

PAKStatus createPAKs(UserToken token, String[] pak_ids) throws RemoteException;

PAKStatus createPAKs(UserToken token, String[] pak_ids, String folder) throws 
RemoteException;

PAKStatus createPAKs(UserToken token, PAK[] paks) throws RemoteException;

PAKStatus createPAKs(UserToken token, PAK[] paks, String folder) throws RemoteException;

Description

This function creates PAK objects in the inventory. The input array of pak_ids is used as the name for each instance of the PAK object. If the input parameter folder is provided, the newly created PAK is added to the folder.

The third and fourth forms of the function take the array of PAK objects as the input parameter. These two functions allow you to create a PAK object and fill in the attributes.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
pak_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of PAK IDs, used as Name for each instance of PAK object.
folder	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The name of the folder. Note Some forms of this function do not require a folder name.
paks	Array of PAK, mandatory	PAK object	An array of PAK objects.

Return

This function returns PAKStatus objects. The following example shows the error code, error messages, and returned objects in the status:

			PAKStatus status = createPAKs(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			PAKStatusItem[] items = status.getPAKStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual object returned by the operation.

			PAK pak = items[i].getPAK();

			// Get the individual error code corresponding to 

			// the object.

				int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the object.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs on an element in the input array, a status object is returned with information about the error.

deletePAKs

Synopsis

IDStatus deletePAKs(UserToken token, String[] pak_ids) throws RemoteException;

Description

This function deletes PAK objects from the inventory using the given PAK IDs. The PAK IDs are obtained from the createPAKs or readPAKs functions. This function also removes a PAK from the folders that it belongs.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
pak_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of PAK IDs.

Return

This function returns IDStatus objects. The following example shows the error code, error messages, and returned objects in the status:

			IDStatus status = deletePAKs(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			IDStatusItem[] items = status.getIDStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual ID returned by the operation.

			String id = items[i].getID();

			// Get the individual error code corresponding to 

			// the ID.

			int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the ID.

			String item_err_msg = items[i].getErrorMessage();

		}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs on an element in the input array, a status object is returned with information about the error.

listAllFoldersByPAK

Synopsis

String[] listAllFoldersByPAK(UserToken token, String[] pak_id) throws RemoteException;

Description

This function returns a list of all folders to which the PAK belongs.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
pak_id	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of PAK IDs, which is used as the ID for each instance of the PAK object.

Return

This function returns an array of folders to which the given PAK belongs. If the PAK does not exist, a non-null array of size zero is returned.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs, this function returns null.

listAllPAKsInFolder

Synopsis

String[] listAllPAKsInFolder(UserToken token, String folder) throws RemoteException;

Description

This function returns an array of PAK IDs that belong to the given folder. If the input folder is null, this function returns an array of PAK IDs in the default folder.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
folder	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	Name of the PAK folder, or null if the function is looking for ungrouped PAKs.

Return

This function returns an array of PAK IDs in the specified folder. If the folder does not exist, it returns null. If the folder is empty, it reutrns a non-null array of size zero.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs, this function returns null.

listPAKContainFeatures

Synopsis

String[] listPAKContainFeatures(UserToken token, String[] features) throws 
RemoteException;	

Description

This function returns a list of PAKs that contains all the license features in the given feature list.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
features	Array of string, mandatory	Features is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of string that represents the license feature names. The array of string is an AND relationship.

Return

This function returns an array of string. Each string is a PAK ID.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When error occurs, this function returns null. An array length of zero means no PAK was found.

readPAKs

Synopsis

PAKStatus readPAKs(UserToken token, String[] pak_ids) throws RemoteException;

Description

This function retrieves an array of PAK objects from the inventory using the given PAK IDs. PAK IDs are obtained from the creatPAKs function.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
pak_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of PAK IDs.

Return

This function returns PAKStatus objects. The following example shows the error code, error messages, and returned objects in the status:

			PAKStatus status = readPAKs(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			PAKStatusItem[] items = status.getPAKStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual object returned by the operation.

			PAK pak = items[i].getPAK();

			// Get the individual error code corresponding to 

			// the object.

				int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the object.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs on an element in the input array, a status object is returned with information about the error.

writePAKs

Synopsis

IDStatus writePAKs(UserToken token, PAK[] pak) throws RemoteException;

Description

This function writes the given PAK objects into the inventory. The input PAK objects can be new instances of PAK returned by the createPAKs() function or existing ones retrieved from the inventory by the readPAKs() function.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
paks	Array of PAK, mandatory	PAK object	An array of PAK objects.

Return

This function returns IDStatus objects. The following example shows the error code, error messages, and returned objects in the status:

			IDStatus status = writePAK(..., ...);

			// The general error code of the operation.

			int err_code = status.getErrorCode();

			// The general error message of the operation.

			String err_msg = status.getErrorMessage();

			// A list of status for each individual element in the 

			// bulk operation.

			IDStatusItem[] items = status.getIDStatusItems()

			// Iterate through the list to get individual status.

		for (int i = 0; i < items.length(); i++) {

			// Get the individual ID returned by the operation.

			String id = items[i].getID();

			// Get the individual error code corresponding to 

			// the ID.

				int item_err_code = items[i].getErrorCode();

			// Get the individual error message corresponding to 

			// the ID.

				String item_err_msg = items[i].getErrorMessage();

			}

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs on an element in the input array, a status object is returned with information about the error.