ossNAS5GWrapper.py

The OSS NAS/Python 5G 16.8.0 Module

The OSS NAS/Python 5G 16.8.0 module contains the createNAS5GInstance() convenience function, which helps you create a SimpleOssNASEncoderDecoderInstance object, and constants. The SimpleOssNASEncoderDecoderInstance object provides methods used to convert a NAS binary message to or from XML or JSON format.

To create a SimpleOssNASEncoderDecoderInstance object, first instantiate a SimpleOssNASEncoderDecoder object. Pass as an argument the path to the OSS NAS/C runtime library (it is included in your OSS NAS Tools for Python installation):

>>> from ossNAS5GWrapper import *
>>> ossWrapper = SimpleOssNASEncoderDecoder("../lib/libossNAS.so")

Next, issue a call to createNAS5GInstance(). Pass as an argument the SimpleOssNASEncoderDecoder object created in the previous step:

>>> ossObject = createNAS5GInstance(ossWrapper)

The ossObject thus obtained can be used to encode and decode NAS messages by calling one of the following methods: ossNASBinary2XML, ossNASBinary2JSON, ossNASXML2Binary, or ossNASJSON2Binary.

>>> nasEncodedData = bytes([0x7e, 0x0, 0x5c, 0x0, 0x1, 0x0)]
>>> xmlEncodedData = ossObject.ossNASBinary2XML(nasEncodedData)
>>> print(xmlEncodedData.decode("utf-8"))
ossNAS5GWrapper.createNAS5GInstance(ossWrapper)

Creates and returns an ossWrapper.SimpleOssNASEncoderDecoderInstance object.

This object provides methods that are used to convert a NAS binary message to or from XML or JSON format.

Parameters:ossWrapper – A previously instantiated ossWrapper.SimpleOssNASEncoderDecoder object.
Raises:OssError.
ossNAS5GWrapper.OSSNAS_PDUNUM

int: Currently has no effect, and is only available for forward compatibility.

ossNAS5GWrapper.OSSNAS_NASVER

bytes: NAS version string

ossWrapper.py

The OSS NAS/C Python Wrapper

The OSS NAS/C Python wrapper is the main Python module. It implements the NAS message conversion functionality.

The module contains classes that make the encoding and decoding functionalities of the underlying OSS NAS/C runtime library easier to access.

Notably, the module contains the SimpleOssNASEncoderDecoder class, which loads and initializes the NAS/C runtime library, and the SimpleOssNASEncoderDecoderInstance class, which provides methods for decoding/encoding a NAS binary messages to or from JSON or XML message format.

class ossWrapper.SimpleOssNASEncoderDecoderInstance(ossLib, world, pduID)

Provides methods that are used to convert a NAS binary message to or from XML or JSON format.

The class also provides error reporting and diagnostic capabilities.

The methods that are used to convert NAS messages are Python wrappers around the corresponding OSS NAS/C library routines.

Parameters:
  • ossLib (ctypes.CDLL) – Reference to the loaded OSS NAS/C runtime library.
  • world (bytes) – Memory buffer used by the underlying OSS NAS/C runtime library.
  • pduID (int.) – A variable set to ossNAS5GWrapper.OSSNAS_PDUNUM.
Raises:

OssError.
ossNASBinary2JSON(nasData)

Converts a binary encoded NAS message to JSON format.

Parameters:nasData – The binary encoded NAS message to be converted.
Returns:The JSON encoded message.
Return type:bytes.
Raises:OssError.
ossNASBinary2XML(nasData)

Converts a binary encoded NAS message to XML format.

Parameters:nasData – The binary encoded NAS message to be converted.
Returns:The XML encoded message.
Return type:bytes.
Raises:OssError.
ossNASGetErrInfo()

Retrieves information about severe error messages and warning messages generated by the latest call to ossNASBinary2JSON() or ossNASBinary2XML().

This method returns more information than the ossNASGetErrMsg() method does.

Returns:
Return type:OssNASErrInfo.
ossNASGetErrMessage()

Retrieves severe error messages generated by the latest call to ossNASBinary2JSON() and ossNASBinary2XML().

Return type:bytes.
ossNASGetOriginator()

Returns the originator previously set by the ossNASSetOriginator().

Returns:When successful, it returns the previously set originator. Otherwise, if it was not previously set, it returns a value of 0 or, under special circumstances, it returns None.
ossNASJSON2Binary(jsonData)

Converts a JSON encoded NAS message to binary.

Parameters:jsonData – The JSON encoded NAS message to be converted.
Returns:The binary encoded NAS message.
Return type:bytes.
Raises:OssError.
ossNASPrintS(text)

Prints a binary (C-style) string to standard output.

Parameters:text (bytes) – The string to be written.
ossNASPrintStr(fmt, text)

Prints formatted string output to standard output.

Parameters:
  • fmt (bytes) – The binary (C-style) string to be written. Should contain a C-style string format specifier, %s which will replaced by the value specified by the text argument.
  • text (bytes) – Additional binary (C-style) string argument to replace the %s format specifier in the fmt argument.
ossNASPrintStrInt(fmt, text, nr)

Prints formatted string output to standard output.

Parameters:
  • fmt (bytes) – The binary (C-style) string to be written. Must contain a C-style string format specifier, %s, and a C-style int format specifier, e.g.: %d, in this order, which will be replaced by the values specified by the next arguments.
  • text (bytes) – Additional binary (C-style) string argument to replace the %s format specifier in the fmt argument.
  • nr (int) – Additional int argument to replace the int format specifier in the fmt argument.
ossNASSetOriginator(originator)

Sets the originator of a NAS message.

In the NAS protocol, certain messages can only be sent by one of the two originators, OSSNAS_ORIG_UE or OSSNAS_ORIG_NETWORK, and the interpretation of other messages depends on the originator of the message.

Parameters:originator – NAS message originator, either OSSNAS_ORIG_UE or OSSNAS_ORIG_NETWORK.
Returns:When successful, it returns the previously set originator. Otherwise, if it was not previously set, it returns a value of 0 or, under special circumstances, it returns None.
ossNASXML2Binary(xmlData)

Converts an XML encoded NAS message to binary.

Parameters:xmlData – The XML encoded NAS message to be converted.
Returns:The binary encoded NAS message.
Return type:bytes.
Raises:OssError.
ossWrapper.OSSNAS_ORIG_UE

int: UE NAS message originator

ossWrapper.OSSNAS_ORIG_NETWORK

int: Network NAS message originator

class ossWrapper.OssError(text, retcode, errmsg, errdesc, do_exit)

Raised on any operation that results in a fatal error.

Operations that can result in a fatal error include wrapper instantiation or initialization or any encoding or decoding operation.

The exception wraps errors returned by calls to the underlying NAS/C runtime library functions.

Variables:
  • context (bytes.) – Additional textual information displayed in case of an error, for example, the name of the NAS/C runtime library function the error originated from.
  • errno (int.) – An integer variable that contains the return code of the NAS/C runtime library function.
  • errmsg (bytes.) – A short textual description of the error.
  • errdesc (bytes.) – A detailed description of the error. It includes information about the message field structure.
  • fatal (bool.) – Specifies if the error is fatal or recoverable.
class ossWrapper.OssNASErrInfo(errorMessages, numberOfErrorConditionsOccurred, numberOfErrorMessagesLogged, warningMessages, numberOfWarningConditionsOccurred, numberOfWarningMessagesLogged)

Represents error information returned by ossWrapper.SimpleOssNASEncoderDecoderInstance.ossNASGetErrInfo().

Variables:
  • errorMessages (bytes.) – is set to a buffer that contains one or more severe error messages in textual form. Each error message in the buffer is terminated by a newline character and is immediately followed by the next error message.
  • numberOfErrorConditionsOccurred (int.) – is set to the total number of severe error conditions that occurred during the operation.
  • numberOfErrorMessagesLogged (int.) – is set to the number of error messages that were generated and added to the error message buffer during the operation. This number equals numberOfErrorConditionsOccurred if the error message buffer is large enough to contain error messages for all the error conditions that occurred, otherwise it is less than numberOfErrorConditionsOccurred.
  • warningMessages (bytes.) – is set to the address of a buffer that contains one or more warning messages in textual form. Each warning message in the buffer is terminated by a newline character and is immediately followed by the next warning message.
  • numberOfWarningConditionsOccurred (int.) – is set to the total number of warning conditions that occurred during the operation.
  • numberOfWarningMessagesLogged (int.) – is set to the number of warning messages that were generated and added to the warning message buffer during the operation. This number equals numberOfWarningConditionsOccurred when the warning message buffer is large enough to contain warning messages for all the warning conditions that occurred; otherwise it is less than numberOfWarningConditionsOccurred.
class ossWrapper.SimpleOssNASEncoderDecoder(ossLibPath)

This is a conceptual class representation of a simple OSS NAS encoder/decoder.

The OSS NAS encoder/decoder is a wrapper around the OSS NAS/C library that implements the encoder/decoder functionality and is created by providing the path to this library.

To convert NAS binary messages to or from XML or JSON format, first create an instance of the SimpleOssNASEncoderDecoderInstance class by issuing a call to ossWrapper.SimpleOssNASEncoderDecoder.createInstance(). The SimpleOssNASEncoderDecoderInstance class instance provides methods used to convert NAS binary messages to or from XML or JSON format.

Parameters:ossLibPath (bytes.) – Path to the OSS NAS/C library, which implements the encoder decoder functionality.
createInstance(nasVer, pduID)

Creates and returns a SimpleOssNASEncoderDecoderInstance class instance.

Parameters:
Raises:

OssError.