TOP

NAS/C 5G API Functions Reference

Applies to: NAS/C 5G r15.6.0 v7.1.8

This section lists the functions in the NAS/C 5G API in alphabetical order.

int ossNASBinary2JSON(OssNASGlobal *world, int pdunum, int sourceRules, OssBuf *binSource, OssBuf *jsonTarget);

Converts an encoded PDU to JSON.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
An integer variable set to OSSNAS_PDUNUM.
sourceRules
Is set to OSSNAS_ENCRULE.
binSource
Pointer to an OssBuf structure whose value field references the binary encoded value and whose length field contains the length in bytes of this value.
jsonTarget
Pointer to an OssBuf structure whose value field references the JSON output text.

Note: The pduNum and sourceRules parameters have been included in this function so that it closely resembles the ossBinary2JSON function of the OSS ASN.1 API. The values of these parameters are ignored in the present version of the OSS NAS API, but should be set to OSSNAS_PDUNUM and OSSNAS_ENCRULE, respectively, for compatibility with future versions of the OSS NAS API.

You can set the value field of jsonTarget to NULL and the length field to zero before calling this function to allow the OSS NAS runtime to automatically allocate and determine the length of the needed space for the output. In such a case, you can call ossNASFreeBuf() on the jsonTarget.value field to free up the automatically allocated memory when it is no longer needed. Alternatively, you can pre-allocate your own memory buffer for the output and set the value field to reference it and the length field to contain the length in bytes of the allocated buffer. In such a case, you should call your standard memory deallocation function to free up the used memory when it is no longer needed.

Note: The final size of the JSON output produced by this function may be smaller than the total space in the JSON output buffer needed during the execution of this function. This happens when the input data contains one or more invalid components that are discarded when the data is decoded. If you want to get an idea of the size typically needed for an JSON output buffer for this function, you should submit to this function a variety of encodings that do not contain any invalid components.

Errors and Warnings

This function can generate multiple error or warning messages. See the Errors and Warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

ossNASBinary2JSON() returns an integer. If the input was successfully converted, a value of zero is returned. Otherwise, the error code of the first severe or recoverable error that occurred is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you can also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.


int ossNASBinary2XML(OssNASGlobal *world, int pdunum, int sourceRules, OssBuf *binSource, OssBuf *xmlTarget);

Converts an encoded PDU to XML.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
An integer variable set to OSSNAS_PDUNUM.
sourceRules
Is set to OSSNAS_ENCRULE.
binSource
Pointer to an OssBuf structure whose value field references the binary encoded value and whose length field contains the length in bytes of this value.
xmlTarget
Pointer to an OssBuf structure whose value field will reference the XML output text.

Note: The pduNum and sourceRules parameters have been included in this function so that it closely resembles the ossBinary2XML function of the OSS ASN.1 API. The value of these parameters are ignored in the present version of the OSS NAS API, but should be set to OSSNAS_PDUNUM and OSSNAS_ENCRULE, respectively, for compatibility with future versions of the OSS NAS API.

You can set the value field of xmlTarget to NULL and the length field to zero before calling this function to allow the OSS NAS runtime to automatically allocate and determine the length of the needed space for the output. In such a case, you can call ossNASFreeBuf() on the xmlTarget.value field to free up the automatically allocated memory when it is no longer needed. Alternatively, you can preallocate your own memory buffer for the output and set the value field to reference it and the length field to contain the length in bytes of the allocated buffer. In such a case, you should call your standard memory deallocation function to free up the used memory when it is no longer needed.

Note: The final size of the XML output produced by this function may be smaller than the total space in the XML output buffer needed during the execution of this function. This happens when the input data contains one or more invalid components that are discarded when the data is decoded. If you want to get an idea of the size typically needed for an XML output buffer for this function, you should submit to this function a variety of encodings that do not contain any invalid components.

Errors and Warnings

This function can generate multiple error or warning messages. See the Errors and Warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

The ossNASBinary2XML() function returns an integer. If the input was successfully converted, a value of zero is returned. Otherwise, the error code of the first severe or recoverable error that occurred is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you can also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.


int ossNASCmpValue(OssNASGlobal *world, int pdunum, void *value1, void *value2);

Compares two variables of type NAS5GS1560_NASMessage (defined in the NAS5GS1560.h file) allowing you to see if they are equal. The two values are considered equal if their encodings are identical bit by bit. The values of any read-only fields present in the two variables are irrelevant for the purpose of the comparison.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
An integer variable set to OSSNAS_PDUNUM.
value1 and value2
The addresses of two unencoded or decoded PDUs to compare. The two PDUs can have an arbitrarily complex structure.

Errors and Warnings

This function can generate multiple error or warning messages. See the Errors and warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

The ossNASCmpValue() function returns an integer. Upon a successful call, a value of zero is returned if the two data structures are equal and a value of 1 is returned if they are not equal. The global enumerator OSSNAS_BAD_ARG is returned if value1 or value2 is NULL. If one or more errors occur during the operation, the error code of the first severe or recoverable error that occurred is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you can also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage1, NASmessage2;
. . . .
if(!ossNASCmpValue(world, pdunum, NASmessage1, NASmessage2)
	ossNASPrint(world, "Values are equal.\n");

See Also

ossNASCpyValue()


int ossNASCpyValue(OssNASGlobal *world, int pdunum, void *source, void **destination);

Copies unencoded/decoded PDUs into an identical structure. The values of any read-only fields present in the source variable are not copied into the corresponding fields of the destination variable. Any read-only fields of the destination variable are set to the appropriate values required by the specification.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
An integer variable set to OSSNAS_PDUNUM.
source
The address of the PDU which contains the data to be copied.
destination
The address of a pointer that will reference the newly copied data. If a preallocated buffer is not provided for the new copy, *destination must be set to NULL. If a preallocated buffer is provided, the length of the buffer must be set with the ossNASSetDecodingLength() function. After a successful return, the pointer destination will reference a copy of the data structure referenced by source.

Errors and Warnings

This function can generate multiple error or warning messages. See the Errors and Warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

The ossNASCpyValue() function returns an integer. Upon a successful call, a value of zero is returned. The global enumerator OSSNAS_BAD_ARG is returned if source or destination is NULL. If one or more errors occur during the operation, the error code of the first severe or recoverable error that occurred is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you can also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.

Example

OssNASGlobal w, *world = &w;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage *NASmessage, *copiedValue = NULL;
int rc;
. . . .
ossNASPrint(world, "\nCopying the Decoded PDU...\n");
rc = ossNASCpyValue(world, pdunum, NASmessage, &copiedValue);
if (rc) {
	ossNASPrint(world, "ossNASCpyValue failed with return code = %d\n", rc);
	error = rc;
}
. . . .
ossNASFreePDU(world, pdunum, copiedValue);
ossNASterm(world);

See Also


int ossNASDecode(OssNASGlobal *world, int *pdunum, OssBuf *input, void **output);

Is used to decode an encoded PDU contained in a buffer of type OssBuf. This function fills a specified variable of type NAS5GS1560_NASMessage (defined in the NAS5GS1560.h file) with values by decoding the encoding of a similar structure (PDU).

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
Pointer to an integer variable set to OSSNAS_PDUNUM.
input
The address of an OssBuf variable whose value field references the encoded PDU to be decoded and whose length field holds the length in bytes of this encoded PDU.
output
The address of a pointer to the memory block designated to hold the decoded PDU.

Note: The pduNum parameter has been included in this function so that this function closely resembles the ossDecode function of the OSS ASN.1 API. The value at the address pointed to by the pduNum parameter is ignored in the present version of the OSS NAS API, but should be set to OSSNAS_PDUNUM for compatibility with future versions of the OSS NAS API.

If the address of a NULL pointer is passed as the fourth argument, the decoder automatically allocates enough memory to hold the decoded data. On the other hand, if you preallocate a buffer for the decoded data and pass the address of the pointer referencing your preallocated buffer, the decoder simply writes the decoded PDU to your provided buffer. Note, however, that after preallocating an output buffer and before calling the decoder each time, you have to call the ossNASSetDecodingLength() function to inform the decoder about the length of the allocated buffer. After a successful return, the decoded data is accessible through the pointer output.

If a severe error condition occurs and the decoding buffer was preallocated, it is possible that the fields of the preallocated output area were updated; consequently, the contents are unpredictable and should not be used. However, if you instructed the decoder to allocate the memory for output data (by passing an address to a NULL pointer as a fourth parameter), the decoder cleans up any temporary memory it allocated before exiting and its output will still point to the NULL pointer.

Determinant fields

Certain fields present in a NAS message play a special role in an encoding. Some of those special fields (e.g., numberOfElements in TAIListElement) are used to indicate the number of elements in a list. Some (messageType in Plain5GSNASMessage) are used to indicate which alternative of a choice is present in the value. Some (e.g., the mccMNCIndicator field in MobileIdentity) are used to indicate whether an optional component of a sequence is present or absent in the value. We call these special fields determinant fields.

In all such cases, the OSS NAS/C API takes the following approach with regard to decoding:

  • The determinant field occurs as a regular field within the C structures defined in the NAS5GS1560 file.
  • The C structures also contain several auxiliary fields (bit_mask fields, choice fields, length fields, etc.).
  • When the ossNASDecode function returns successfully, any determinant fields present in the C structures are set to the correct values.
  • The auxiliary fields present in the C structures are set by the decoder in accordance with the corresponding determinant fields; for example, a bit_mask field at the beginning of a struct is set to a value that indicates whether each optional component of a sequence is present or absent (as indicated by the determinant field); a choice field followed by a union at the beginning of a struct is set to a value that indicates which alternative of a choice is present (as indicated by the determinant field); a length field for a bit string is set to a value that indicates the length (in bits) of a bit string value; and so on.

We recommend that after calling ossNASDecode, the user application utilize the auxiliary fields (bit_mask fields, choice fields, length fields, etc.) rather than the determinant fields (mccMNCIndicator, numberOfElements, messageType, etc.). The auxiliary fields carry all the relevant information in a way that is explicit and consistent across the entire specification. In contrast, using a determinant field directly requires ad-hoc processing for each different determinant field.

The user application could be interested in the value of a determinant field for other reasons, such as when the field conveys some specific information in addition to acting as a determinant for some other field of the message. In this case, the application can utilize an auxiliary field (e.g., a choice field) to know, for example, which alternative of a choice is present, and use the value of the determinant field for the additional information it conveys.

Errors and Warnings

This function can generate multiple error or warning messages. See the Errors and Warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

The ossNASDecode() function returns an integer. If the input was successfully decoded, a value of zero is returned. If one or more errors occur during the operation, the error code of the first severe or recoverable error that occurred is returned. See the Return Codes section for details on the possible return codes and their meanings. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you can also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.

The number of bytes occupied by the decoded data can be retrieved by a call to ossNASGetFinalDecodingLength().

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS1560_NASMessage *NASmessagePtr = NULL; /* address of decoded data */
int pdu_num = OSSNAS_PDUNUM;
. . . .
if (ossNASDecode(world, &pdu_num, &encodedData, (void **)&NASmessagePtr))
{
	ossNASPrint(world, "%s\n", ossNASGetErrMsg(world)); 
		/* one or more errors occurred, print errmsg */
	ossNASterm(world);
	retcode = 1;
} 
else
{ /* Print out the data that was just decoded. */
	ossNASPrint(world, "\nData decoded to:\n\n"); /* successfully decoded */
	ossNASPrintPDU(world, pdu_num, NASmessagePtr);
	ossNASFreePDU(world, pdu_num, NASmessagePtr); /* free up PDU */
	retcode = 0;
}

See Also


int ossNASDecodeJSON(OssNASGlobal *world, int *pdunum, OssBuf *input, void **output);

Is used to decode a JSON encoded PDU contained in a buffer of type OssBuf. This function fills a specified variable of type NAS5GS1560_NASMessage with values by decoding the encoding of a similar structure (PDU).

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
Pointer to an integer variable set to OSSNAS_PDUNUM.
input
The address of an OssBuf variable whose value field references the encoded PDU to be decoded and whose length field holds the length in bytes of this encoded PDU.
output
The address of a pointer to the memory block designated to hold the decoded PDU.

Note: The pduNum parameter has been included in this function so that this function closely resembles the ossDecode function of the OSS ASN.1 API. The value at the address pointed to by the pduNum parameter is ignored in the present version of the OSS NAS API, but should be set to OSSNAS_PDUNUM for compatibility with future versions of the OSS NAS API.

If the address of a NULL pointer is passed as the fourth argument, the decoder automatically allocates enough memory to hold the decoded data. On the other hand, if you preallocate a buffer for the decoded data and pass the address of the pointer referencing your preallocated buffer, the decoder simply writes the decoded PDU to your provided buffer. Note, however, that after preallocating an output buffer and before calling the decoder each time, you have to call the ossNASSetDecodingLength() function to inform the decoder about the length of the allocated buffer. After a successful return, the decoded data is accessible through the pointer output.

If a severe error condition occurs and the decoding buffer was preallocated, it is possible that the fields of the preallocated output area were updated; consequently, the contents are unpredictable and should not be used. However, if you instructed the decoder to allocate the memory for output data (by passing an address to a NULL pointer as a fourth parameter), the decoder cleans up any temporary memory it allocated before exiting and its output will still point to the NULL pointer.

Errors

This function can generate only a single error message. Note that it generates an error when the input message contains an unknown or repeated Information Element.

Return Value

The ossNASDecodeJSON() function returns an integer. When the input is successfully decoded, a value of zero is returned. When an error occurs during the operation, an error code is returned. See the Return Codes section for details on the possible return codes and their meanings. Upon failure, you can use the ossNASGetErrMsg() function to determine what went wrong. The number of bytes occupied by the decoded data can be retrieved by a call to ossNASGetFinalDecodingLength().

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS1560_NASMessage *NASmessagePtr = NULL; /* address of decoded data */
int pdu_num = OSSNAS_PDUNUM;
. . . .
if (ossNASDecodeJSON(world, &pdu_num, &encodedData, (void **)&NASmessagePtr))
{
	ossNASPrint(world, "%s\n", ossNASGetErrMsg(world)); 
		/* one or more errors occurred, print errmsg */
	ossNASterm(world);
	retcode = 1;
} 
else
{ /* Print out the data that was just decoded. */
	ossNASPrint(world, "\nData decoded to:\n\n"); /* successfully decoded */
	ossNASPrintPDU(world, pdu_num, NASmessagePtr);
	ossNASFreePDU(world, pdu_num, NASmessagePtr); /* free up PDU */
	retcode = 0;
}

See Also


int ossNASDecodeXML(OssNASGlobal *world, int *pdunum, OssBuf *input, void **output);

Is used to decode an XML encoded PDU contained in a buffer of type OssBuf. This function fills a specified variable of type NAS5GS1560_NASMessage with values by decoding the encoding of a similar structure (PDU).

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
Pointer to an integer variable set to OSSNAS_PDUNUM.
input
The address of an OssBuf variable whose value field references the encoded PDU to be decoded and whose length field holds the length in bytes of this encoded PDU.
output
The address of a pointer to the memory block designated to hold the decoded PDU.

Note: The pduNum parameter has been included in this function so that this function closely resembles the ossDecode function of the OSS ASN.1 API. The value at the address pointed to by the pduNum parameter is ignored in the present version of the OSS NAS API, but should be set to OSSNAS_PDUNUM for compatibility with future versions of the OSS NAS API.

If the address of a NULL pointer is passed as the a fourth argument, the decoder automatically allocates enough memory to hold the decoded data. On the other hand, if you preallocate a buffer for the decoded data and pass the address of the pointer referencing your preallocated buffer, the decoder simply writes the decoded PDU to your provided buffer. Note, however, that after preallocating an output buffer and before calling the decoder each time, you have to call the ossNASSetDecodingLength() function to inform the decoder about the length of the allocated buffer. After a successful return, the decoded data is accessible through the pointer output.

If a severe error condition occurs and the decoding buffer was preallocated, it is possible that the fields of the preallocated output area were updated; consequently, the contents are unpredictable and should not be used. However, if you instructed the decoder to allocate the memory for output data (by passing an address to a NULL pointer as a fourth parameter), the decoder cleans up any temporary memory it allocated before exiting and its output will still point to the NULL pointer.

Errors

This function can generate only a single error message. Note that it generates an error if the input message contains an unknown or repeated Information Element.

Return Value

TheossNASDecodeXML() function returns an integer. When the input is successfully decoded, a value of zero is returned. When an error occurs during the operation, an error code is returned. See the Return Codes section for details on the possible return codes and their meanings. Upon failure, you can use the ossNASGetErrMsg() function to determine what went wrong. The number of bytes occupied by the decoded data can be retrieved by a call to ossNASGetFinalDecodingLength().

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS1540_NASMessage *NASmessagePtr = NULL; /* address of decoded data */
int pdu_num = OSSNAS_PDUNUM;
. . . .
if (ossNASDecodeXML(world, &pdu_num, &encodedData, (void **)&NASmessagePtr))
{
	ossNASPrint(world, "%s\n", ossNASGetErrMsg(world)); 
		/* one or more errors occurred, print errmsg */
	ossNASterm(world);
	retcode = 1;
} 
else
{ /* Print out the data that was just decoded. */
	ossNASPrint(world, "\nData decoded to:\n\n"); /* successfully decoded */
	ossNASPrintPDU(world, pdu_num, NASmessagePtr);
	ossNASFreePDU(world, pdu_num, NASmessagePtr); /* free up PDU */
	retcode = 0;
}

See Also


char *ossNASDescribeReturnCode(OssNASGlobal *world, int retcode);

Is used for getting a textual description of the numeric return code obtained from any ASN.1 API function.

Arguments

world
Pointer to the global OSS NAS environment variable.
retcode
An integer variable that contains the return code obtained from any ASN.1 API function.

Unlike the ossNASGetErrMsg() function that only works with the ossNASEncode() and ossNASDecode() functions, the ossNASDescribeReturnCode() function can be used in conjunction with any OSS NAS/C API function (including the above-mentioned ones).

Return Value

The ossNASDescribeReturnCode() function returns a pointer to a string containing the description of the given return code. If the return code is invalid or unknown, NULL is returned.

Example

OssNASGlobal w, *world = &w;
int retcode;
char *msg = NULL;
. . . .
if ((retcode = ossNASinit(world, "NAS5GS1560"))) {
	#ifndef DLL_LINKAGE
	msg = ossNASDescribeReturnCode(NULL, retcode);
	#endif /* DLL_LINKAGE */
	ossNASPrint(NULL, "ossNASinit() returned %d: \"%s\"\n", retcode,
	msg ? msg : "<no description>");
	return retcode;
}
. . . .

long ossNASDetermineEncodingLength(OssNASGlobal *world, int pdunum, void *data);

Returns the size of the encoded data that ossNASEncode() would create if it were called to encode the sent PDU. This function allows you to find the size of the buffer needed to store the encoder's output. The prime use of this function is in those applications that want to minimize the amount of memory allocated.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
An integer variable set to OSSNAS_PDUNUM.
data
The address of the data structure whose encoding length is desired.

Errors and Warnings

This function can generate multiple error and/or warning messages. See the Errors and Warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

The ossNASDetermineEncodingLength() function returns a long integer. Upon a successful call, the number of octets to be occupied by the data's encoding is returned; otherwise, a length of zero is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you can also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage;
long encodingLength;
. . . .
encodingLength = ossNASDetermineEncodingLength(world, pdunum, &NASmessage);
ossNASPrint(world, "Encoding Length: %ld.\n", encodingLength);

See Also

ossNASEncode()


int ossNASEncode(OssNASGlobal *world, int pdunum, void *input, OssBuf *output);

Is used to encode a value-filled variable of type NAS5GS1560_NASMessage (defined in the NAS5GS1560.h file) into an encoded PDU.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
An integer variable set to OSSNAS_PDUNUM.
input
The address of the initialized variable of type NAS5GS1560_NASMessage desired for encoding, and output is the address of an OssBuf variable designated to contain the finished encoding.

Note: The pduNum parameter has been included in this function so that this function closely resembles the ossEncode function of the OSS ASN.1 API. The value of the pduNum parameter is ignored in the present version of the OSS NAS API, but should be set to OSSNAS_PDUNUM for compatibility with future versions of the OSS NAS API.

If you initialize the length and value fields of the output OssBuf variable to NULL and zero, respectively, the encoder automatically allocates the space needed for the output buffer. Alternatively if you preallocate a memory buffer by yourself for the finished encoding, you should set the value field of OssBuf to reference the beginning of the buffer and the length field to the length in bytes of the allocated buffer.

After a successful return, the encoded data will be pointed to by the value field of the passed OssBuf variable. In addition, the length field of the OssBuf variable will contain the length in bytes of the finished encoding.

Determinant fields

Certain fields present in a NAS message play a special role in an encoding. Some of those special fields (e.g., numberOfElements in TAIListElement) are used to indicate the number of elements in a list. Some (messageType in PlainNAS5GSMMessage) are used to indicate which alternative of a choice is present in the value. (e.g., the mccMNCIndicator field in MobileIdentity). Some are used to indicate whether a certain optional component is present or absent in the value. We call these special fields determinant fields. In all such cases, the OSS NAS/C API takes the following approach with regard to encoding:

  • The determinant field occurs as a regular field within the C structures defined in the NAS5GS1560.h file.
  • The C structures also contain several auxiliary fields (bit_mask fields, choice fields, length fields, etc.).
  • The encoder uses the auxiliary fields, not the determinant fields, to know whether an optional component is present, which choice alternative is selected, and so on; the encoded value will reflect the intent of the user application as conveyed by the auxiliary fields.
  • The encoder verifies that the value of each determinant field is consistent with the value of the corresponding auxiliary field; if the values are consistent, the encoder uses the value of the determinant field as the source value for the encoding; otherwise, the encoder ignores the original value of the determinant field and uses the lowest valid value for the determinant field that is consistent with the value of the auxiliary field.

In most cases, the user application does not need to set the determinant fields present in a variable before calling ossNASEncode. The application must set all the auxiliary fields properly, whether or not it also sets any determinant fields, and therefore setting a determinant field is usually pointless.

In some cases, though, the user application could want to set a determinant field (in addition to the corresponding auxiliary field). This is when the determinant field conveys some specific information in addition to acting as a determinant for some other field of the message. In such cases, there are multiple values of the determination field that correspond to the same value of the auxiliary field, and any of those values will be accepted by the encoder and used as the source value for the encoding.

Read-only fields

Certain fields present in a NAS message are specified as read-only and their values are ignored by the encode operation. Those fields include most determinant fields as well as all the fields that are constrained by the 3GPP NAS technical specification to have a fixed value. You can know whether a field is read-only by looking for the READONLY keyword inside a comment within the NAS5GS1560.h file. The ossNASPrintPDU() function prints the <!--AUTO--> comment before the value of a read-only field.

You do not need to assign a value to any read-only fields present in the C structures prior to calling the ossNASEncode() function or any other function that performs an encode operation (ossNASPrintPDU(), ossNASCpyValue(), ossNASCmpValue(), and ossNASDetermineEncodingLength()). You do not need to worry about initializing those fields to zeros, for example, since their values are ignored.

As an important example, your application does not need to set (or even initialize) the messageType field within Plain5GSNASMessage or NAS5GSMMessage prior to calling ossNASEncode(). It only needs to set the choice field under the body field (of type TPlainmessageBody or TSMMmessageBody, respectively). The value of the messageType field is ignored by the ossNASEncode() function.

Errors and Warnings

This function can generate multiple error or warning messages. See the Errors and Warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

The ossNASEncode() function returns an integer. If the input was successfully encoded, a value of zero is returned. If one or more errors occur during the operation, the error code of the first severe or recoverable error that occurred is returned. See the Return Codes section for details on the possible return codes and their meanings. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you can also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.

Warning: Beware, if you preallocate an output buffer, ossNASEncode() may alter the value field of the OssBuf variable to point to a location within the output buffer. Therefore, always retain a separate copy of the beginning address of the preallocated buffer. Doing so allows you to use the same buffer for your next call to ossNASEncode(). In addition, a separate copy of this pointer is useful for freeing up the buffer after you are done using it.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS1560_NASMessage NASmessage;
. . . .
encodedData.value = NULL; /* Initialize encoder output buffer */
encodedData.length = 0;
/* Encode the data. Return non-zero for failure. */
if (ossNASEncode(world, OSSNAS_PDUNUM, &NASmessage, &encodedData)) 
{
	ossNASPrint(world, "%s\n", ossNASGetErrMsg(world)); 
		/* one or more errors occurred, print errmsg */
	ossNASterm(world); /* Free up allocated resources */
	return 1;
}

In this example, NASmessage is the data structure intended for encoding. Refer to the Example section to see a complete example.

See Also


void ossNASFreeBuf(OssNASGlobal *world, void *encodedData);

Is used to free up memory allocated by ossNASEncode(). Typically, this allocated memory is contained in the value field of the OssBuf variable.

Arguments

world
Pointer to the global OSS NAS environmental variable.
encodedData
Pointer to a buffer containing encoded data.

After a successful return, the sent memory buffer is freed up.

Return Value

The ossNASFreeBuf() function does not return a value. Note: If you preallocated your own memory buffer before calling the encoder, do not use the ossNASFreeBuf() function. Instead, use your own routines for freeing up such memory.

Example

OssNASGlobal w, *world = &w;
OssBuf yourEncodedData; /* length and address of encoded data */
int pdunum = OSSNAS_PDUNUM;
. . . .
if (retcode = ossNASEncode(world, pdunum, &NASmessage, &yourEncodedData))
{ /* one or more errors occurred, print errmsg */
	ossNASPrint(world, "%s\n", ossNASGetErrMsg(world));
	. . . .
	ossNASFreeBuf(world, yourEncodedData.value);
}

Refer to the Example section to see a complete example.

See Also

ossNASFreePDU()


void ossNASFreeMemory(OssNASGlobal *world, void *ptr);

Deallocates a block of memory that has been previously allocated by ossNASGetMemory(). It is also possible to deallocate the encoder (decoder) output memory using ossNASFreeMemory() when it is known that a block of memory has been allocated by the encoder (decoder) and is not (for example) a pointer to the input encoding or a stack variable. If custom memory allocation, deallocation, and reallocation functions are installed by setting the mallocp, freep, and realloc fields of the OssNASGlobal structure, a custom memory deallocation function will be used to free the memory.

Arguments

world
Pointer to the global OSS NAS environmental variable.
ptr
A block of memory to deallocate.

Return Value

The ossNASFreeMemory() function does not return a value.

Example

#define BUF_SIZE 1024
OssNASGlobal w, *world = &w;
OssBuf buf;
. . . .
buf.value = (unsigned char *)ossNASGetMemory(world, BUF_SIZE);
buf.length = BUF_SIZE;
. . . . /* call OSS NAS/C API functions using 'buf' */
ossNASFreeMemory(world, buf);

See Also

ossNASGetMemory()


int ossNASFreePDU(OssNASGlobal *world, int pdunum, void *data);

Is used to free up memory allocated by the ossNASDecode() and ossNASCpyValue() functions.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
An integer variable set to OSSNAS_PDUNUM.
data
Pointer to the decoded or copied PDU.

After a successful return, the sent memory buffer is freed up.

Return Value

The ossNASFreePDU() function returns an integer. If the memory was successfully freed up, a value of zero is returned; otherwise, a non-zero value is returned.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS1560_NASMessage *NASmessagePtr = NULL; /* address of decoded data */
int pdu_num = OSSNAS_PDUNUM;
. . . .
if (ossNASDecode(world, &pdu_num, &encodedData, (void **)&NASMessagePtr))
	. . . .
else
{ /* Print out the data that was just decoded. */
	ossNASPrint(world, "\nData decoded to:\n\n"); /* successfully decoded */
	ossNASPrintPDU(world, pdu_num, NASmessagePtr);
	ossNASFreePDU(world, pdu_num, NASmessagePtr); /* free up PDU */
	retcode = 0;
}

Refer to the Example section to see a complete example.

This function cannot be used to free data structures that you yourself allocated. If you preallocated the output buffer passed to the decoder, do not use ossNASFreePDU() to free it.

See Also

ossNASFreeBuf()


unsigned long ossNASGetDecodingFlags(OssNASGlobal *world);

Returns the logical OR of the decoder-applicable flags set by ossNASSetFlags() and ossNASSetDecodingFlags() functions.

Arguments

world
Pointer to the global OSS NAS environmental variable.

The only flags defined in the present version of the OSS NAS/C API are OSSNAS_RESERVEDFLAG1, OSSNAS_RESERVEDFLAG2, and OSSNAS_RESERVEDFLAG3, all of them reserved. Do not use these flags.

Return Value

The ossNASGetDecodingFlags() function returns an unsigned long integer. Upon a successful call, all of the flags in place for the decoder are returned. Otherwise, a value of (unsigned long)-1 is returned if world was found to be NULL and a value of zero is returned if no prior call had been made to ossNASSetFlags(), ossNASSetEncodingFlags(), or ossNASSetDecodingFlags() functions.

Example

OssNASGlobal w, *world = &w;
unsigned long flags;
. . . .
flags = ossNASGetDecodingFlags(world);
if (flags & FLAG1)
	ossNASPrint(world, "FLAG1 is being used.\n");
else
	ossNASPrint(world, "FLAG2 is NOT being used.\n");

See Also


long ossNASGetDecodingLength(OssNASGlobal *world);

Returns the total number of bytes in the decoded data buffer used during the last call to the ossNASDecode() function. In some cases, the size returned by this function is larger than the final size of the decoded data produced by the ossNASDecode() function. The larger size returned by this function is the minimum size actually required for the decoded data buffer.

Arguments

world
The global OSS NAS environmental variable passed to the ossNASDecode() function when decoding the data whose length you want to know.

Return Value

The ossNASGetDecodingLength() function returns a long integer. Upon a successful call, the total number of bytes occupied by the last decoded PDU is returned; otherwise, a value of -1 is returned.

Note: ossNASSetDecodingLength() overwrites the last decoding length stored by the decoder. Thus, you should call ossNASGetDecodingLength() after calling ossNASDecode() and before calling ossNASSetDecodingLength().

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage, *NASmessagePtr;
long lengthOfDecodedData;
. . . .
ossNASDecode(world, &pdunum, &encodedData, (void **)&NASmessagePtr);
lengthOfDecodedData = ossNASGetDecodingLength(world);

In the above example, the length of the decoder's output will be available in the lengthOfDecodedData variable.

See Also


long ossNASGetFinalDecodingLength(OssNASGlobal *world);

Returns the number of bytes in the decoded data buffer occupied by the output of last call to the ossNASDecode() function. The decoded data consists of a single continuous block of data in the output buffer.

Arguments

world
The global OSS NAS environmental variable passed to the ossNASDecode() function when decoding the data whose length you want to know.

Return Value

The ossNASGetFinalDecodingLength() function returns a long integer. Upon a successful call, the total number of bytes occupied by the last decoded PDU is returned; otherwise, a value of -1 is returned. Note: ossNASSetDecodingLength() overwrites the last decoding length stored by the decoder. Thus, you should call ossNASGetFinalDecodingLength() after calling ossNASDecode() and before calling ossNASSetDecodingLength().

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage, *NASmessagePtr;
long lengthOfDecodedData;
. . . .
ossNASDecode(world, &pdunum, &encodedData, (void **)&NASmessagePtr);
lengthOfDecodedData = ossNASGetDecodingLength(world);

In the above example, the length of the decoder's output will be available in the lengthOfDecodedData variable.

See Also

ossNASSetDecodingLength()


unsigned long ossNASGetEncodingFlags(OssNASGlobal *world);

Returns the flags set by the ossNASSetFlags() and ossNASSetEncodingFlags() functions.

Arguments

world
Pointer to the global OSS NAS environmental variable.

The only flags defined in the present version of the OSS NAS/C API are OSSNAS_RESERVEDFLAG1, OSSNAS_RESERVEDFLAG2, and OSSNAS_RESERVEDFLAG3, all of them reserved. Do not use these flags.

Return Value

The ossNASGetEncodingFlags() function returns an unsigned long integer. Upon a successful call, all of the flags in place for the encoder are returned. A value of (unsigned long)-1 is returned if world was found to be NULL and a value of zero is returned if no prior call had been made to ossNASSetFlags(), ossNASSetEncodingFlags(), or ossNASSetDecodingFlags() functions.

Example

OssNASGlobal w, *world = &w;
unsigned long flags;
. . . .
flags = ossNASGetEncodingFlags(world);
if (flags & FLAG1)
	ossNASPrint(world, "FLAG1 is being used.\n");
else
	ossNASPrint(world, "FLAG1 is NOT being used.\n");

See Also


int ossNASGetErrInfo(OssNASGlobal *world, OssNASErrInfo *errinfo)); ;

Retrieves information about severe error messages, recoverable error messages, and warning messages generated by the latest call to ossNASEncode(), ossNASDecode(), ossNASPrintPDU(), ossNASBinary2JSON(), ossNASBinary2XML(), ossNASCpyValue(), ossNASCmpValue(), or ossNASDetermineEncodedLength(). This function returns more information than the ossNASGetErrMsg() function does.

Arguments

world
Pointer to the global OSS NAS environmental variable passed to the encoder or decoder.
errinfo
Pointer to a variable of the following type:
typedef struct OssNASErrInfo {
	const char *errorMessages; 
	int numberOfErrorConditionsOccurred; 
	int numberOfErrorMessagesLogged; 
	const char *warningMessages; 
	int numberOfWarningConditionsOccurred; 
	int numberOfWarningMessagesLogged; 
} OssNASErrInfo;

This function fills the above output structure as follows:

  • errorMessages is set to the address of a buffer containing one or more severe or recoverable error messages in textual form (US-ASCII). Each error message in the buffer is terminated by a newline character and is immediately followed by the next error message.
  • numberOfErrorConditionsOccurred is set to the total number of severe and recoverable error conditions that occurred during the operation.
  • numberOfErrorMessagesLogged is set to the number of error messages that were generated and added to the error message buffer during the operation. This number equals numberOfErrorConditionsOccurredif 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 is set to the address of a buffer containing one or more warning messages in textual form (US-ASCII). Each warning message in the buffer is terminated by a newline character and is immediately followed by the next warning message.
  • numberOfWarningConditionsOccurred is set to the total number of warning conditions that occurred during the operation.
  • numberOfWarningMessagesLogged 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 if the warning message buffer is large enough to contain warning messages for all the warning conditions that occurred, otherwise it is less than numberOfWarningConditionsOccurred.

If many recoverable error conditions occur during an encode or decode operation, the error message buffer may not be large enough to contain error messages for all of them. At some point during the operation, the error message buffer may become full. If that happens, no more messages are added to the error message buffer until the end of the operation. You can know whether this has happened by comparing numberOfErrorConditionsOccurred with numberOfErrorMessagesLogged.

Likewise, if many warning conditions occur during the operation, the warning message buffer may not be large enough to contain warning messages for all of them. At some point during the operation, the warning message buffer may become full. If that happens, no more messages are added to the warning message buffer until the end of the operation. You can know whether this has happened by comparing numberOfWarningConditionsOccurred with numberOfWarnigMessagesLogged.

Note that after the error message buffer (or the warning message buffer) becomes full, no more messages are added to it regardless of their size. A new message will not be added even if it is shorter than the message that caused the buffer to become full and the remaining space at the end of the buffer is large enough to contain the message.

Note that the two buffers are independent. A new error message will be added to the error message buffer even if the warning message buffer has become full, so long as the error message buffer itself has not become full. Likewise, a new warning message will be added to the warning message buffer even if the error message buffer has become full, so long as the warning message buffer itself has not become full.

Note that the last message added to the error or warning message buffer will always be complete and terminated by a newline character.

This function does not alter the state of the OSS NAS/C API runtime environment.

Return Value

The ossNASGetErrMsg() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage;
OssNASErrInfo errinfo;
. . . .
ossNASPrint(world, "Starting encoder... \n");
ossNASEncode(world, pdunum, &NASmessage, &encodedData);
ossNASGetErrInfo(world, &errinfo);

In the above example, the ossNASGetErrInfo() function will retrieve information about the error and warning conditions that were generated during the call to ossNASEncode(). If ossNASEncode() returns a failure code (non-zero for failure), the error message buffer returned by the ossNASGetErrInfo() function will contain one or more severe or recoverable error messages. The warning message buffer returned by the function may contain one or more warning messages whether or not the ssNASEncode() call fails.

See Also


char *ossNASGetErrMsg(OssNASGlobal *world);

Retrieves severe and recoverable error messages generated by the latest call to ossNASEncode(), ossNASDecode(), ossNASPrintPDU(), ossNASBinary2JSON(), ossNASBinary2XML(), ossNASCpyValue(), ossNASCmpValue(), or ossNASDetermineEncodedLength(). This function should be called when ossNASEncode() and ossNASDecode() return a nonzero value.

Arguments

world
Pointer to the global OSS NAS environmental variable passed to the encoder or decoder.

This function returns the address of a buffer containing one or more severe or recoverable error messages in textual form (US-ASCII). Each error message in the buffer is terminated by a newline character and is immediately followed by the next error message.

This function provides a simple method for obtaining the error messages produced by an encode or decode operation. If you need additional details about the errors and warnings produced by the operation, you can call the ossNASGetErrInfo() function.

If many recoverable error conditions occur during an encode or decode operation, the error message buffer may not be large enough to contain error messages for all of them. At some point during the operation, the error message buffer may become full. If that happens, no more messages are added to the error message buffer until the end of the operation. This condition is not reported by this function, but you can call the ossNASGetErrInfo() function to know whether some error messages could not be added to the error message buffer.

The first error message present in the buffer is the one that describes the return value returned by the encode or decode function. In some cases, you may only be interested in the first error message produced by an encode/decode operation. In such cases, you can utilize the characters returned by this function up to the first newline character and ignore the rest of the string.

This function does not alter the state of the OSS NAS/C API runtime environment.

Return Value

The ossNASGetErrMsg() function returns a character string pointer. If the encoder/decoder experienced one or more severe or recoverable error conditions during the latest call, the character string is the concatenation of all the error messages produced, each terminated by a newline character, in the order in which they were produced. If the call to the encoder/decoder did not generate any severe or recoverable error messages, an empty character string ("") is returned. If the call to the encoder/decoder generated one or more warnings but no errors, an empty character string is also returned. Finally, NULL is returned if the sent OssNASGlobal variable was NULL.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage;
. . . .
ossNASPrint(world, "Starting encoder... \n");
if(ossNASEncode(world, pdunum, &NASmessage, &encodedData))
	ossNASPrint(world, "%s\n", ossNASGetErrMsg(world));

In the above example if ossNASEncode() returns a failure code (non-zero for failure), the ossNASGetErrMsg() function will retrieve the error messages that were produced during the call. Finally, ossNASPrint() will display the retrieved error messages.

See Also


int ossNASJSON2Binary(OssNASGlobal *world, int *pdunum, OssBuf *input, OssBuf *output);

Converts a textual JSON NAS message to binary encoded format. The JSON format should be the same as the JSON format produced by ossNASBinary2JSON().

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
Pointer to an integer variable set to OSSNAS_PDUNUM.
input
Pointer to an OssBuf structure whose value field references the JSON NAS message and whose length field contains the length of this value in bytes.
output
Pointer to an OssBuf structure whose value field references the binary NAS message.

NOTE: The value of the pdunum parameter is ignored in the present version of the OSS NAS API, but should be set to point to an integer variable set to OSSNAS_PDUNUM for compatibility with future versions of the OSS NAS API.

You can set the value field of output to NULL and the length field to zero before calling this function to allow the OSS NAS runtime to automatically allocate and determine the length of the needed space for the output. In such a case, you can call ossNASFreeBuf() on the output.value field to free up the automatically allocated memory when it is no longer needed. Alternatively, you can pre-allocate your own memory buffer for the output and set the value field to reference it and the length field to contain the length in bytes of the allocated buffer. In such a case, you should call your standard memory deallocation function to free up the used memory when it is no longer needed.

Errors

This function can generate only a single error message. Note that it generates an error when the input message contains an unknown or repeated Information Element.

Return Value

ossNASJSON2Binary() returns an integer. If the input was successfully converted, a value of zero is returned. Otherwise, the error code of the first error that occurred is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong.


int ossNASXML2Binary(OssNASGlobal *world, int *pdunum, OssBuf *input, OssBuf *output);

Converts a textual XML NAS message to binary encoded form. The XML format should be the same as the XML format produced by ossNASBinary2XML().

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
Pointer to an integer variable set to OSSNAS_PDUNUM.
input
Pointer to an OssBuf structure whose value field references the XML NAS message and whose length field contains the length of this value in bytes.
output
Pointer to an OssBuf structure whose value field references the binary NAS message.

NOTE: The value of this parameter is ignored in the present version of the OSS NAS API, but should be set to point to an integer variable set to OSSNAS_PDUNUM for compatibility with future versions of the OSS NAS API.

You can set the value field of output to NULL and the length field to zero before calling this function to allow the OSS NAS runtime to automatically allocate and determine the length of the needed space for the output. In such a case, you can call ossNASFreeBuf() on the output.value field to free up the automatically allocated memory when it is no longer needed. Alternatively, you can preallocate your own memory buffer for the output and set the value field to reference it and the length field to contain the length in bytes of the allocated buffer. In such a case, you should call your standard memory deallocation function to free up the used memory when it is no longer needed.

Errors

This function can generate only a single error message. Note that it generates an error when the input message contains an unknown or repeated Information Element.

Return Value

The ossNASXML2Binary() function returns an integer. If the input was successfully converted, a value of zero is returned. Otherwise, the error code of the first error that occurred is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong.


OSS_UINT32 ossNASGetExtendedProtocolDiscriminator (OssNASGlobal *world);
 OSS_UINT32 ossNASGetMessageType (OssNASGlobal *world);
 OSS_UINT32 ossNASGetPduSessionIdentity (OssNASGlobal *world);
 OSS_UINT32 ossNASGetProcedureTransactionIdentity (OssNASGlobal *world);

 ossBoolean ossNASHasExtendedProtocolDiscriminator (OssNASGlobal *world);
 ossBoolean ossNASHasMessageType (OssNASGlobal *world);
 ossBoolean ossNASHasPduSessionIdentity (OssNASGlobal *world);
 ossBoolean ossNASHasProcedureTransactionIdentity (OssNASGlobal *world);

NAS applications can use these ossNASGet*() functions to retrieve the corresponding IE values of a binary NAS message even when the message decoding fails with an unrecoverable error, provided these values are present in the message; otherwise, the functions will return a value of 0XFFFF. These functions are useful when preparing an error response as specified in Section 7 of 3GPP TS 24.501.

Arguments

world
The OSS NAS global environment variable.

Return Value

These ossNASGet*() functions return the decoded value of the corresponding IE as an unsigned 32-bit integer when the IE is present in the message and has been decoded; otherwise they return 0xFFFF.
The ossNASHas*() functions are helper functions that return 1 when the corresponding IE is present in the message and has been decoded; otherwise they return 0.

Note: The values returned by the ossNASGet*() functions are also directly available as the corresponding fields of the ossNASGlobal structure, for example,

world->extendedProtocolDiscriminator

The ossNASDecode() function sets these ossGlobal fields to 0xFFFF before decoding starts and then updates them as the corresponding IEs are decoded.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS1560_NASMessage *NASmessagePtr = NULL; /* address of decoded data */
int pdu_num = OSSNAS_PDUNUM;
. . . .
rc = ossNASDecode(world, &pdu_num, &encodedData, (void **)&NASmessagePtr);
if (rc) {
  if (rc == OSSNAS_TooShortMessage) {
     /* ignore message */
  } else { /* messageType and procedureTransactionIdentity were decoded */
     msgtype = ossNASGetMessageType(world); /* access via the API */
     pti = world->procedureTransactionIdentity; /* access via OssGlobal */
     if ((msgType == pduSessionModificationComplete
              || msgType == pduSessionReleaseComplete
              || msgType == pduSessionModificationCommandReject)
           && ! isInUsePTI(pti)) {
        /* respond with 5GSM STATUS with 5GSM cause #47 "PTI mismatch" */
     }
     if (msgType == pduSessionAuthenticationComplete
           && isAssignedPTI(pti)) {
        /* respond with 5GSM STATUS with 5GSM cause #81 "invalid PTI value */
     }
     if ((msgType == pduSessionEstablishmentRequest
              || msgType == pduSessionModificationRequest
              || msgType == pduSessionModificationRequest
              || msgType == pduSessionReleaseRequest)
           && ! isAssignedPTI(pti)) {
        /* respond with 5GSM STATUS with 5GSM cause #81 "invalid PTI value */
     }
     if (pti == 255
         && world->extendedProtocolDiscriminator =
                                 nas5GSSessionManagementMessages) {
        /* ignore message */
     }
  }
}

See Also


unsigned long ossNASGetFlags(OssNASGlobal *world);

Returns the logical OR of the flags set by the ossNASSetFlags(), ossNASSetEncodingFlags(), or ossNASSetDecodingFlags() function.

Arguments

world
Pointer to the global OSS NAS environmental variable.

The only flags defined in the present version of the OSS NAS/C API are OSSNAS_RESERVEDFLAG1, OSSNAS_RESERVEDFLAG2, and OSSNAS_RESERVEDFLAG3, all of them reserved. Do not use these flags.

Return Value

The ossNASGetFlags() function returns an unsigned long integer. Upon a successful call, the logical OR of all the flags in place in the encoder and decoder is returned. A value of (unsigned long)-1 is returned if world was found to be NULL and a value of zero is returned if no prior call had been made to ossNASSetFlags(), ossNASSetEncodingFlags(), or ossNASSetDecodingFlags() function.

Note: Calling this function is equivalent to taking logical OR of the return values of the ossNASGetEncodingFlags() and ossNASGetDecodingFlags() functions.

Example

OssNASGlobal w, *world = &w;
unsigned long flags;
. . . .
flags = ossNASGetFlags(world);
if (flags & (FLAG1 | FLAG2))
	ossNASPrint(world, "FLAG1 and FLAG2 in use\n");
else if(flags & FLAG3)
	ossNASPrint(world, "FLAG3 in use\n");

See Also


void *ossNASGetMemory(OssNASGlobal *world, size_t size);

Allocates a block of memory in exactly the same way as OSS NAS/C API functions like ossNASEncode() and ossNASDecode() would do. In particular, if custom memory allocation, deallocation, and reallocation functions were set by setting the mallocp, freep, and realloc fields of the OssNASGlobal structure, the custom memory allocator will be used to get the memory.

Arguments

world
Pointer to the global OSS NAS environment variable.
size
Indicates the size of memory (in bytes) to be allocated.

Return Value

The ossNASGetMemory() function returns a pointer to the newly allocated block of memory. This block is available to the application until it is explicitly deallocated by a call to the ossNASFreeMemory() function. Upon a failure, the function returns NULL.

See Also

ossNASFreeMemory()


unsigned long ossNASGetOriginator(OssNASGlobal *world);

Returns the originator previously set by the ossNASSetOriginator() function. The originator (OSSNAS_ORIG_UE or OSSNAS_ORIG_NETWORK) is the type of endpoint that creates and sends a NAS message (UE or network, respectively).

Arguments

world
Pointer to the global OSS NAS environmental variable.

Return Value

The ossNASGetOriginator() function returns an integer. Upon a successful call, either OSSNAS_ORIG_UE or OSSNAS_ORIG_NETWORK is returned. Otherwise, a value of (unsigned long)-1 is returned if world was found to be NULL and a value of zero is returned if no prior call had been made to the ossNASSetOriginator() function.

Example

OssNASGlobal w, *world = &w;
int originator;
. . . .
originator = ossNASGetOriginator(world);

switch(originator)
{	
	case OSSNAS_ORIG_UE:
		ossNASPrint(world, "The current originator is the UE.\n");
		break;
	case OSSNAS_ORIG_NETWORK:
		ossNASPrint(world, "The current originator is the Network.\n");
		break;
	default:
		ossNASPrint(world, "Originator not set.\n");
		break;
}

See Also

ossNASSetOriginator().


int ossNASinit(OssNASGlobal *world, const char *NASversion);

Is used to initialize a global environment variable of type OssNASGlobal. This function must be called before any of the other OSS NAS/C API functions are used.

Arguments

world
Pointer to the global OSS NAS environmental variable.
NASversion
A character string specifying a version of 3GPP NAS. To use 3GPP 5GS v5GS 15.6.0 specify "NAS5GS1560" as the second argument of this function.

After a successful return, all necessary initializations are performed and the other OSS NAS/C API functions can be safely called.

If you want to use two or more versions of 3GPP NAS simultaneously in your application, you must allocate one distinct OssNASGlobal variable for each 3GPP NAS version that you want to use, and must call ossNASinit once for each version, passing the corresponding OssNASGlobal variable as well as the NAS version string (see the second example below). To work with more than one NAS version simultaneously, your application must be linked with dynamic OSS NAS libraries.

Return Value

The ossNASinit() function returns an integer. Upon a successful initialization, a value of zero is returned; otherwise, a non-zero value is returned.

Note: If your application uses multiple simultaneous threads, you should keep a separate unshared instance of the OssNASGlobal structure for each thread.

Example 1

OssNASGlobal w, *world = &w;
. . . .
ossNASinit(world, "NAS5GS1560");

Refer to the Example section to see a complete example.

Example 2

OssNASGlobal wNAS1280, *worldNAS1280 = &wNAS1280;
OssNASGlobal wNAS5GS1560, *worldNAS5GS1560 = &wNAS5GS1560;
. . . .
ossNASinit(worldNAS1280, "NAS1280");
ossNASinit(worldNAS5GS1560, "NAS5GS1560");

/* use world1280 to work with NAS 12.8.0 messages */
/* use world5GS1560 to work with NAS 5GS 15.6.0
 messages */

ossNASterm(worldNAS1280);
ossNASterm(worldNAS5GS1560);

See Also

ossNASterm()


int ossNASPrint(OssNASGlobal *world, const char *format, ...);

Serves as a replacement to the C printf() and fprintf() functions.

Arguments

world
Pointer to the global OSS NAS environmental variable.

The rest of the parameters are exactly the same as those of printf().

After a successful return, the sent string is printed to the device pointed to by the asn1out field of the OssNASGlobal structure.

Return Value

The ossNASPrint() function returns an integer. Upon a successful call, the number of bytes written is returned; otherwise, a value of -1 is returned.

Example

OssGlobal w, *world = &w;
OssBuf encodedData;
int myPduNum = OSSNAS_PDUNUM;
MyASN1DataType myData;
. . . .
ossNASPrint(world, "Starting encoder... \n");
ossNASEncode(world, myPduNum, &myData, &encodedData);
ossNASPrint(world, "Finished encoding\n");

See Also

ossNASPrintPDU()


int ossNASPrintNAS(OssNASGlobal *world, int *pdunum, OssBuf *binSource, OssBuf *traceBuf, int *numberOfRecords);

Produces a report of the structure of a NAS encoding. The report consists of a sequence of records of type OssPrintNASRecord (defined in the ossNAS.h file), one for each field, information element, or other group of fields of the structure. Each record contains information about a field, such as name, type, start offset, end offset, value, and a pointer to the parent field.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
Pointer to an integer variable set to OSSNAS_PDUNUM.
binSource
Pointer to an OssBuf structure whose value field references the binary encoded value and whose length field contains the length in bytes of this value.
traceBuf
Pointer to an OssBuf structure whose value field references the report produced by the function.
numberOfRecords
Pointer an integer variable that is set to the number of records in the report.

You can set the value field of traceBuf to NULL and the length field to zero before calling this function to allow the OSS NAS runtime to automatically allocate and determine the length of the needed space for the output. In such a case, you can call ossNASFreeBuf() on the traceBuf.value field to free up the automatically allocated memory when it is no longer needed. Alternatively, you can pre-allocate your own memory buffer for the output and set the value field to reference it and the length field to contain the length in bytes of the allocated buffer. In such a case, you should call your standard memory deallocation function to free up the used memory when it is no longer needed.

After a successful return, the buffer pointed to by the value field of the traceBuf variable will contain an array of values of type OssPrintNASRecord, and the numberOfRecords variable will indicate how many records there are in the array. The OssPrintNASRecord type is defined as follows:

typedef struct OssPrintNASRecord
{
	unsigned char *fieldName;
	unsigned int startBitOffset;
	unsigned int endBitOffset;
	int type;
	unsigned int index;
	int signedValue;
	unsigned int length;
	unsigned char *stringBody;
	struct OssPrintNASRecord *parent;
} OssPrintNASRecord;

The fields of this structure have the following meanings:

  • fieldName points to a null-terminated ASCII string containing the name of the field.
  • startBitOffset is the offset of the first bit of the field from the beginning of the encoding.
  • endBitOffset is the offset of the last bit of the field from the beginning of the encoding.
  • type indicates the type of the field (1: sequence, 2: choice, 3: sequence-of, 4: null, 5: boolean, 6: enumerated, 7: integer, 8: octet string, 9: bit string, 10: character string).
  • index contains the value of a field whose type is boolean or enumerated (for example, for a boolean field, 0 means false and 1 means true).
  • signedValue contains the value of a field whose type is integer.
  • length contains the length of the value of a field whose type is octet string, bit string, character string, or sequence-of.
  • stringBody contains the body of the value of a field whose type is octet string, bit string, or character string.
  • parent contains a pointer to the record corresponding to the parent of this field (it is NULL in the first record).

Notes: Certain NAS fields (e.g., MCC and MNC) have a complex encoding in which the range of bits between the first bit of the field and the last bit of the field may include material belonging to a neighboring field. For these fields, the difference endBitOffset – startBitOffset is not equal to the actual number of bits of the field.

In addition, several NAS fields appear out of order in the report because the NAS encoding requires that they be allocated on the lower nibble of an octet or on the upper nibble of an octet which is not the next nibble in the encoding.

Errors and Warnings

This function can generate multiple error or warning messages. See the Errors and Warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

The ossNASPrintNAS() function returns an integer. Upon a successful call, a value of zero is returned. If one or more errors occur during the operation, the error code of the first severe or recoverable error that occurred is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you may also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.

See Also


int ossNASPrintPDU(OssNASGlobal *world, int pdunum, void *data);

Allows values in variables of type NAS5GS1560_NASMessage (defined in the NAS5GS1560.h file) to be printed before encoding or after decoding. The values of any read-only fields present in the input variable are printed "as is" and are prefixed with the "<!--AUTO-->" comment. The ossNASDecode() function sets these fields to their proper values. The ossNASEncode() function ignores the values of such fields.

Arguments

world
Pointer to the global OSS NAS environmental variable.
pdunum
Integer variable set to OSSNAS_PDUNUM.
data
The address of this data structure for printing.

After a successful return, the sent data structure is printed out in XML form to the device pointed to by the asn1out field of the OssNASGlobal structure.

Errors and Warnings

This function can generate multiple error or warning messages. See the Errors and Warnings section for a discussion of this feature and for information on how to retrieve the error and warning messages generated by your function call.

Return Value

The ossNASPrintPDU() function returns an integer. Upon a successful call, a value of zero is returned. If one or more errors occur during the operation, the error code of the first severe or recoverable error that occurred is returned. Upon failure, you can use the ossNASGetErrMsg() function or the ossNASGetErrInfo() function to determine what went wrong. If the operation succeeds, you can also use the ossNASGetErrInfo() function if you are interested in the warnings that may have been produced.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage;
. . . .
strcpy(tempStr, "A NAS message.\0");
ossNASPrintPDU(world, pdunum, &NASmessage);

ossNASPrintPDU() output:

<?xml version="1.0" encoding="UTF-8"?>
<NASMessage>
    <nas5GMMMessage>
        <plain>
            <extendedProtocolDiscriminator><!--AUTO-->126</extendedProtocolDiscriminator>
            <securityHeaderType>0</securityHeaderType>
            <spare><!--AUTO-->0</spare>
            <messageType><!--AUTO--></messageType>
            <messageBody>
                <registrationRequest>
                    <nas5GSRegistrationType>
                        <for>1</for>
                        <nas5GSRegistrationTypeValue>1</nas5GSRegistrationTypeValue>
                    </nas5GSRegistrationType>
                    <ngKSI>
                        <tsc>0</tsc>
                        <nasKeySetIdentifier>4</nasKeySetIdentifier>
                    </ngKSI>
                    <nas5GSMobileIdentity>
                        <nas5GSTMSI>
                            <dummy><!--AUTO-->0</dummy>
                            <typeOfIdentity><!--AUTO-->0</typeOfIdentity>
                            <amfSetID>0</amfSetID>
                            <amfPointer>2</amfPointer>
                            <nas5GTMSI>02041725</nas5GTMSI>
                        </nas5GSTMSI>
                    </nas5GSMobileIdentity>
                    <nas5GMMCapability>
                        <spare><!--AUTO-->0</spare>
                        <lpp>1</lpp>
                        <hoAttach>1</hoAttach>
                        <s1Mode>1</s1Mode>
                    </nas5GMMCapability>
                    <networkSlicingIndication>
                        <spare><!--AUTO-->0</spare>
                        <dcni>1</dcni>
                        <nssci>0</nssci>
                    </networkSlicingIndication>
                </registrationRequest>
            </messageBody>
        </plain>
    </nas5GMMMessage>
</NASMessage>

See Also


int ossNASSetDecodingFlags(OssNASGlobal *world, unsigned long flags);

Helps to control the behavior of the ossNASDecode() function.

Arguments

world
Pointer to the global OSS NAS environmental variable.
flags
One or more literals separated by vertical bars ("|").

The only flags defined in the present version of the OSS NAS/C API are OSSNAS_RESERVEDFLAG1, OSSNAS_RESERVEDFLAG2, and OSSNAS_RESERVEDFLAG3, all of them reserved. Do not use these flags.

After a successful return, the sent flag is set to modify the behavior of the decoder starting on its next call.

Return Value

The ossNASSetDecodingFlags() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.

The ossNASSetFlags() function can also be used to set flags for the decoder.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage, *NASmessagePtr;
. . . .
ossNASSetDecodingFlags(world, ossNASGetDecodingFlags(world) | 
		FLAG1 | FLAG2 | FLAG3);
ossNASDecode(world, &pdunum, &encodedData, (void **)&NASmessagePtr);

See Also


int ossNASSetDecodingLength(OssNASGlobal *world, long bufferLength);

Is used by applications that preallocate memory for the decoder's output buffer. This function makes the length of the preallocated memory buffer available to the decoder at runtime. The ossNASSetDecodingLength() function must be called prior to every invocation of ossNASDecode(), if you preallocated the decoder's output buffer.

Arguments

world
Pointer to the global OSS NAS environmental variable.
bufferLength
The length in bytes of the preallocated decoder output buffer. This argument is referenced by the ossNASDecode() function only if the ossNASDecode() is sent a non-NULL value in its output field.

After a successful return, the length of the preallocated decoder output buffer is available for reference by the decoder.

Return Value

The ossNASSetDecodingLength() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage, *NASmessagePtr;
. . . .
ossNASSetDecodingLength(world, 1024);
ossNASDecode(world, &pdunum, &encodedData, (void **)&NASmessagePtr);

In the above example, the decoder's preallocated output buffer has a length of 1024 bytes.

Note: The set buffer length is only referenced by the decoder if the sent output buffer pointer is non-NULL.

See Also

ossNASGetDecodingLength()


int ossNASSetEncodingFlags(OssNASGlobal *world, unsigned long flags);

Helps to control the behavior of the ossNASEncode() function.

Arguments

world
Pointer to the global OSS NAS environmental variable.
flags
One or more literals separated by vertical bars ("|").

The only flags defined in the present version of the OSS NAS/C API are OSSNAS_RESERVEDFLAG1, OSSNAS_RESERVEDFLAG2, and OSSNAS_RESERVEDFLAG3, all of them reserved. Do not use these flags.

After a successful return, the sent flag is set to modify the behavior of the encoder starting on its next call.

Return Value

The ossNASSetEncodingFlags() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage;
. . . .
ossNASSetEncodingFlags(world, ossNASGetEncodingFlags(world) | FLAG1);
ossNASEncode(world, pdunum, &NASmessage, &encodedData);

The ossNASSetFlags() function can also be used to set flags for the encoder.

See Also


int ossNASSetFlags(OssNASGlobal *world, unsigned long flags);

Helps control the behavior of ossNASEncode() and ossNASDecode() functions.

Arguments

world
Pointer to the global OSS NAS environmental variable.
flags
One or more literals separated by vertical bars ("|").

The OSSNAS_IGNORECEFCONSTRAINTS flag relaxes some constraints while encoding and decoding. Some optional Information Elements in NAS messages that are not syntactically correct could still be successfully decoded when this flag is set. Note that the OSSNAS_RESERVEDFLAG1 and OSSNAS_RESERVEDFLAG2 flags are intended for internal use only. Do not use these two flags.

Return Value

The ossNASSetFlags() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.

Warning: Note that each time you call ossNASSetFlags() (or ossNASSetDecodingFlags() or ossNASSetEncodingFlags()), all previous flags set by ossNASSetDecodingFlags(), ossNASSetEncodingFlags(), and ossNASSetFlags() are overwritten. Therefore, if you wish to preserve the previous settings, you should first call ossNASGetFlags() and then perform a logical OR between the returned value and the new flags you want to set. For example:

ossNASSetFlags(world, ossNASGetFlags(world) | FLAG3);

Note: This function performs the same task as the ossNASSetEncodingFlags() and ossNASSetDecodingFlags() functions. However for flags shared by both the encoder and decoder, calling this function is equivalent to calling the ossNASSetEncodingFlags() and ossNASSetDecodingFlags() functions one after the other.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASMessage, *NASMessagePtr;
. . . .
ossNASSetFlags(world, ossNASGetFlags(world) | FLAG1 | FLAG2);
ossNASEncode(world, OSSNAS_PDUNUM, &NASMessage, &encodedData);
. . . .
ossNASSetFlags(world, ossNASGetFlags(world) | FLAG3);
ossNASDecode(world, &pdunum, &encodedData, (void **)&NASMessagePtr);

In the above example, both the ossNASEncode() and ossNASDecode() functions are affected by the first ossNASSetFlags() function call. The second ossNASSetFlags() function call simply adds FLAG3 to the collection of flags that are currently being used (since a logical OR is performed with the existing flags).

See Also


int ossNASSetOriginator(OssNASGlobal *world, int originator);

Sets the originator for a NAS message that will be encoded or decoded. This setting affects the behavior of the ossNASEncode() and ossNASDecode() functions. In the NAS protocol, certain messages can only be sent by one of the two originators, and the interpretation of other messages depends on the originator of the message.

Arguments

world
Pointer to the global OSS NAS environmental variable.
originator
Is either OSSNAS_ORIG_UE or OSSNAS_ORIG_NETWORK.

After a successful return, the originator is set to modify the behavior of the encoder/decoder starting on its next call.

Return Value

The ossNASSetOriginator() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS5GS1560_NASMessage NASmessage;
. . . .
ossNASSetOriginator(world, OSSNAS_ORIG_UE);
ossNASDecode(world, pdunum, &NASmessage, &encodedData);  /* decode a UE-generated message */
ossNASSetOriginator(world, OSSNAS_ORIG_NETWORK);
ossNASEncode(world, pdunum, &NASmessage, &encodedData);  /* encode a Network-generated message */

See Also

ossNASGetOriginator()


void ossNASterm(OssNASGlobal *world);

Is used upon completion of use of the OSS NAS/C API functions. This function is used in conjunction with ossNASinit().

Arguments

world
Pointer to the instance of the OSS NAS global environmental variable to be freed up.

After a successful return, all necessary clean-up activity is finished and your application can safely go on to do other things.

Return Value

The ossNASterm() function does not have a return value.

Note: Each instance of the OssNASGlobal structure must be freed separately using the ossNASterm() function.

Example

OssNASGlobal w, *world = &w;
. . . .
ossNASterm(world);

Refer to the Example section to see a complete example.

See Also

ossNASinit()


This documentation applies to the OSS NAS Tools for C for 5G v7.1.8 for 3GPP Release 15.6.0.

Copyright © 2024 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS NAS Tools for C for 5G is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS NAS Tools for C for 5G are available to you.