This section lists the functions in the OSS NAS/C API in alphabetical order.
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 NAS<version-number>_NASMessage (defined in the NAS<version-number>.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; NAS13100_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;
NAS13100_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 NAS<version-number>_NASMessage (defined in the NAS<version-number>.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., the mccMNCIndicator field in MobileIdentity) are used to indicate whether an optional component of a sequence is present or absent in the value. Some (e.g., numberOfElements in TAIListElement) are used to indicate the number of elements in a list. Some (messageType in PlainEMMMessage) are used to indicate which alternative of a choice is present 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 */
NAS13100_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 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, "NAS13100"))) {
#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; NAS13100_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 NAS<version-number>_NASMessage (defined in the NAS<version-number>.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., the mccMNCIndicator field in MobileIdentity) are used to indicate whether a certain optional component is present or absent in the value. Some (e.g., numberOfElements in TAIListElement) are used to indicate the number of elements in a list. Some (messageType in PlainEMMMessage) are used to indicate which alternative of a choice is present 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 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 NAS<version-number>.h file.
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 PlainEMMMessage or ESMMessage prior to calling ossNASEncode(). It only needs to set the choice field under the body field (of type NAS<version-number>__choice1 or NAS<version-number>__choice2, 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 */
NAS13100_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.
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 */
NAS13100_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; NAS13100_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; NAS13100_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 the severe error, recoverable error, and warning messages generated by the latest call to ossNASEncode(), ossNASDecode(), ossNASPrintPDU(), 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; NAS13100_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 the severe and recoverable error messages generated by the latest call to ossNASEncode(), ossNASDecode(), ossNASPrintPDU(), 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; NAS13100_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.
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 your OSS NAS/C API license includes two or more versions of 3GPP NAS and 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, "NAS13100");
Refer to the Example section to see a complete example.
OssNASGlobal wNAS1280, *worldNAS1280 = &wNAS1280; OssNASGlobal wNAS13100, *worldNAS13100 = &wNAS13100; . . . . ossNASinit(worldNAS1280, "NAS1280"); ossNASinit(worldNAS13100, "NAS13100"); /* use world1280 to work with NAS 12.8.0 messages */ /* use world13100 to work with NAS 13.10.0 messages */ ossNASterm(worldNAS1280); ossNASterm(worldNAS13100);
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");
Allows printing of values in variables of type NAS<version-number>_NASMessage (defined in the NAS<version-number>.h file) before encoding or after decoding. The values of any read-only fields present in the input variable are ignored and printed as zeros.
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;
NAS13100_NASMessage NASmessage;
. . . .
strcpy(tempStr, "A NAS message.\0");
ossNASPrintPDU(world, pdunum, &NASmessage);
ossNASPrintPDU() output:
<?xml version="1.0" encoding="UTF-8"?>
<NASMessage>
<esmMessage>
<protocolDiscriminator>2</protocolDiscriminator>
<epsBearerIdentity>0</epsBearerIdentity>
<procedureTransactionIdentity>25</procedureTransactionIdentity>
<messageType>193</messageType>
<body>
<activateDefaultEPSBearerContextRequest>
<epsQoS>
<qci>244</qci>
</epsQoS>
<accessPointName>
022F9E40 249B25C4 98C11000 E7359164 0C061519 679DB884 DD29F8C4 01843690
5DDF0E19 B0D38C89 001DB1A9 6A8A01A4 86817100 D6
</accessPointName>
<pdnAddress>
<spare>11</spare>
<pdnType>1</pdnType>
<pdnAddressInformation>
<ipv4Address>03319A40</ipv4Address>
</pdnAddressInformation>
</pdnAddress>
<negotiatedQoS>
<spare1>2</spare1>
<delayClass>7</delayClass>
<reliabilityClass>5</reliabilityClass>
<peakThroughput>10</peakThroughput>
<spare2>0</spare2>
<precedenceClass>4</precedenceClass>
<spare3>3</spare3>
<meanThroughput>5</meanThroughput>
<trafficClass>3</trafficClass>
<deliveryOrder>0</deliveryOrder>
<deliveryOfErroneousSDU>1</deliveryOfErroneousSDU>
<maximumSDUSize>3</maximumSDUSize>
<maximumBitRateForUplink>84</maximumBitRateForUplink>
<maximumBitRateForDownlink>184</maximumBitRateForDownlink>
<residualBER>4</residualBER>
<sduErrorRatio>4</sduErrorRatio>
<transferDelay>25</transferDelay>
<trafficHandlingPriority>0</trafficHandlingPriority>
<guaranteedBitRateForUplink>6</guaranteedBitRateForUplink>
<guaranteedBitRateForDownlink>0</guarantedBitRateForDownlink>
<spare4>3</spare4>
<signalingIndication>0</signalingIndication>
<sourceStatisticsDescriptor>9</sourceStatisticsDescriptor>
</negotiatedQoS>
<apnAMBR>
<apnAMBRForDownlink>0</apnAMBRForDownlink>
<apnAMBRForUplink>23</apnAMBRForUplink>
</apnAMBR>
</activateDefaultEPSBearerContextRequest>
</body>
</esmMessage>
</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; NAS13100_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; NAS13100_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; NAS13100_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. Other flags defined in the present version of the OSS NAS/C API are OSSNAS_RESERVEDFLAG1 and OSSNAS_RESERVEDFLAG2, which are both reserved. 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; NAS13100_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 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; NAS13100_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 */
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 LTE/EPC v5.2.1 for 3GPP Release 13.10.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 LTE/EPC 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 LTE/EPC are available to you.