This section lists the functions in the NAS/C 5G API in alphabetical order.
Converts an encoded PDU to JSON.
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.
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.
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.
Converts an encoded PDU to XML.
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.
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.
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.
Compares two variables of type NAS5GS17101_NASMessage (defined in the NAS5GS17101.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.
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.
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.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_NASMessage NASmessage1, NASmessage2; . . . . if(!ossNASCmpValue(world, pdunum, NASmessage1, NASmessage2) ossNASPrint(world, "Values are equal.\n");
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.
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.
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.
We stand with Ukraine 
OssNASGlobal w, *world = &w;
int pdunum = OSSNAS_PDUNUM;
NAS5GS17101_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);
Is used to decode an encoded PDU contained in a buffer of type OssBuf. This function fills a specified variable of type NAS5GS17101_NASMessage (defined in the NAS5GS17101.h file) with values by decoding the encoding of a similar structure (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.
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:
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.
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.
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().
OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS17101_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;
}
Is used to decode a JSON encoded PDU contained in a buffer of type OssBuf. This function fills a specified variable of type NAS5GS17101_NASMessage with values by decoding the encoding of a similar structure (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.
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.
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().
OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS17101_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;
}
Is used to decode an XML encoded PDU contained in a buffer of type OssBuf. This function fills a specified variable of type NAS5GS17101_NASMessage with values by decoding the encoding of a similar structure (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.
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.
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().
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;
}
Is used for getting a textual description of the numeric 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).
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.
OssNASGlobal w, *world = &w;
int retcode;
char *msg = NULL;
. . . .
if ((retcode = ossNASinit(world, "NAS5GS17101"))) {
#ifndef DLL_LINKAGE
msg = ossNASDescribeReturnCode(NULL, retcode);
#endif /* DLL_LINKAGE */
ossNASPrint(NULL, "ossNASinit() returned %d: \"%s\"\n", retcode,
msg ? msg : "<no description>");
return retcode;
}
. . . .
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.
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.
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.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_NASMessage NASmessage; long encodingLength; . . . . encodingLength = ossNASDetermineEncodingLength(world, pdunum, &NASmessage); ossNASPrint(world, "Encoding Length: %ld.\n", encodingLength);
Is used to encode a value-filled variable of type NAS5GS17101_NASMessage (defined in the NAS5GS17101.h file) into an encoded PDU.
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.
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:
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.
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 NAS5GS17101.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.
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.
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.
OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS17101_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.
Extracts into an output array the lengths and positions of the encodings of the ueParametersUpdateList field of the ueParametersUpdateTransparentContainer information elements that are present in a binary DL NAS transport message. By using a returned offset it is easy to find the offsets of the corresponding counterUPU field and the upuMACIAUSF checksum field. The function allows you to calculate and verify the checksum after decoding a message or to calculate and insert the checksum into a newly encoded message.
The function must not be called using a NAS binary message unless the message has been successfully decoded by ossNASDecode() or is the result of a successful encoding by ossNASEncode(). The behavior of the function is unpredictable for invalid NAS binary messages.
Note: The function will stop a search once the entire array has been filled.
Note: Normally, a DL NAS transport message contains at most one UE parameters update list.
ossNASFindUPULists() returns an integer. If the input message is not a DL NAS Transport message or it is too short, the function returns OSSNAS_INVALID_INPUT (-1); otherwise, it returns the number of UEParametersUpdateLists fields that are present.
/* Demonstrates how to access *undecoded* UE parameters update lists,
* counterUPU, and upuMACIAUSF fields in a binary DL NAS TRANSPORT message
*/
#define MAX_LIST_SIZE 4
OssMsgBlock upulists[MAX_LIST_SIZE];
int count = ossNAS5GSFindUPULists(msg, upulists, MAX_LIST_SIZE);
if (count > 0) {
int i;
ossNAS5GSPrint(nasworld, "\n======= UEParametersUpdateLists found: =======\n");
for (i = 0; i < count; i++) {
unsigned int offset = upulists[i].offset;
ossNASPrint(nasworld, "Instance %d:\n", i + 1);
ossNASPrint(nasworld, " counterUPU: %d\n",
msg->value[offset - 2]*256 + msg->value[offset - 1]);
ossNASPrint(nasworld, " upuMACIAUSF: ");
printOctets(nasworld, &msg->value[offset - 18], 16);
ossNAS5GSPrint(nasworld, " upulist(offset %u, length %u): ",
offset , upulists[i].length);
printOctets(nasworld, msg->value + offset, upulists[i].length);
}
ossNAS5GSPrint(nasworld, "===================================\n");
} else if (count == 0)
ossNAS5GSPrint(nasworld, "--- ueParametersUpdateList not found ---\n\n");
else
ossNAS5GSPrint(nasworld, "ERROR: Input message is not a DL NAS transport message or it is too short\n\n");
where printOctets() is defined as follows
static void printOctets(OssNASGlobal *nasworld, unsigned char *value, unsigned int len)
{
static char *digits = "0123456789ABCDEF";
unsigned int i;
for (i = 0; i < len; i++)
ossNAS5GSPrint(nasworld, "%c%c ", digits[value[i] >> 4], digits[value[i] & 0xF]);
ossNAS5GSPrint(nasworld, "\n");
}
Is used to free up memory allocated by ossNASEncode(). Typically, this allocated memory is contained in the value field of the OssBuf variable.
After a successful return, the sent memory buffer is freed up.
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.
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.
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.
The ossNASFreeMemory() function does not return a value.
#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);
Is used to free up memory allocated by the ossNASDecode() and ossNASCpyValue() functions.
After a successful return, the sent memory buffer is freed up.
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.
OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS17101_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.
Returns the logical OR of the decoder-applicable flags set by ossNASSetFlags() and ossNASSetDecodingFlags() functions.
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.
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.
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");
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.
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().
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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.
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.
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().
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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.
Returns the flags set by the ossNASSetFlags() and ossNASSetEncodingFlags() functions.
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.
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.
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");
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.
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:
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.
The ossNASGetErrMsg() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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.
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.
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.
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.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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.
Converts a textual JSON NAS message to binary encoded format. The JSON format should be the same as the JSON format produced by ossNASBinary2JSON().
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.
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.
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.
Converts a textual XML NAS message to binary encoded form. The XML format should be the same as the XML format produced by ossNASBinary2XML().
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.
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.
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.
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.
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.
OssNASGlobal w, *world = &w;
OssBuf encodedData; /* length and address of encoded data */
NAS5GS17101_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 == NAS5GS17101_NAS5GSMMessageType_pduSessionModificationComplete
|| msgType == NAS5GS17101_NAS5GSMMessageType_pduSessionReleaseComplete
|| msgType == NAS5GS17101_NAS5GSMMessageType_pduSessionModificationCommandReject)
&& ! isInUsePTI(pti)) {
/* respond with 5GSM STATUS with 5GSM cause #47 "PTI mismatch" */
}
if (msgType == NAS5GS17101_NAS5GSMMessageType_pduSessionAuthenticationComplete
&& isAssignedPTI(pti)) {
/* respond with 5GSM STATUS with 5GSM cause #81 "invalid PTI value */
}
if ((msgType == NAS5GS17101_NAS5GSMMessageType_pduSessionEstablishmentRequest
|| msgType == NAS5GS17101_NAS5GSMMessageType_pduSessionModificationRequest
|| msgType == NAS5GS17101_NAS5GSMMessageType_pduSessionModificationRequest
|| msgType == NAS5GS17101_NAS5GSMMessageType_pduSessionReleaseRequest)
&& ! isAssignedPTI(pti)) {
/* respond with 5GSM STATUS with 5GSM cause #81 "invalid PTI value */
}
if (pti == 255
&& world->extendedProtocolDiscriminator =
NAS5GS17101_nas5GSSessionManagementMessages) {
/* ignore message */
}
}
}
Returns the logical OR of the flags set by the ossNASSetFlags(), ossNASSetEncodingFlags(), or ossNASSetDecodingFlags() function.
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.
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.
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");
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.
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.
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).
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.
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;
}
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.
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.
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.
OssNASGlobal w, *world = &w; . . . . ossNASinit(world, "NAS5GS17101");
Refer to the Example section to see a complete example.
OssNASGlobal wNAS1280, *worldNAS1280 = &wNAS1280; OssNASGlobal wNAS5GS17101, *worldNAS5GS17101 = &wNAS5GS17101; . . . . ossNASinit(worldNAS1280, "NAS1280"); ossNASinit(worldNAS5GS17101, "NAS5GS17101"); /* use world1280 to work with NAS 12.8.0 messages */ /* use world5GS17101 to work with NAS 5GS 17.10.1 messages */ ossNASterm(worldNAS1280); ossNASterm(worldNAS5GS17101);
Serves as a replacement to the C printf() and fprintf() functions.
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.
The ossNASPrint() function returns an integer. Upon a successful call, the number of bytes written is returned; otherwise, a value of -1 is returned.
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");
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.
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:
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.
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.
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.
Allows printing of values in variables of type NAS5GS17101_NASMessage (defined in the NAS5GS17101.h file) 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.
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.
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.
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.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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>
Helps to control the behavior of the ossNASDecode() function.
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.
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.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_NASMessage NASmessage, *NASmessagePtr; . . . . ossNASSetDecodingFlags(world, ossNASGetDecodingFlags(world) | FLAG1 | FLAG2 | FLAG3); ossNASDecode(world, &pdunum, &encodedData, (void **)&NASmessagePtr);
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.
After a successful return, the length of the preallocated decoder output buffer is available for reference by the decoder.
The ossNASSetDecodingLength() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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.
Helps to control the behavior of the ossNASEncode() function.
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.
The ossNASSetEncodingFlags() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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.
Helps control the behavior of ossNASEncode() and ossNASDecode() functions.
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.
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.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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).
Sets the encoder/decoder operation mode.
When OSS_NAS_MODE is used, the ossNASDecode() function decodes the input binary data into an instance of the NASMessage structure and the ossNASEncode() function encodes the input NASMessage structure into binary NAS data.
When OSS_URSP_MODE is used, the ossNASDecode() function decodes the input binary data into an instance of the UEPolicyManagementMessage structure and the ossNASEncode() function encodes the input UEPolicyManagementMessage structure into binary URSP data.
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.
After a successful return, the originator is set to modify the behavior of the encoder/decoder starting on its next call.
The ossNASSetOriginator() function returns an integer. Upon a successful call, a value of zero is returned; otherwise, a non-zero value is returned.
OssNASGlobal w, *world = &w; OssBuf encodedData; int pdunum = OSSNAS_PDUNUM; NAS5GS17101_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 */
Returns the current operation mode of the encoder/decoder.
Is used upon completion of use of the OSS NAS/C API functions. This function is used in conjunction with ossNASinit().
After a successful return, all necessary clean-up activity is finished and your application can safely go on to do other things.
The ossNASterm() function does not have a return value.
Note: Each instance of the OssNASGlobal structure must be freed separately using the ossNASterm() function.
OssNASGlobal w, *world = &w; . . . . ossNASterm(world);
Refer to the Example section to see a complete example.
This documentation applies to the OSS NAS Tools for C for 5G v9.0.0 for 3GPP Release 17.10.1.
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.