TOP

NAS/C API Functions Reference

Applies to: NAS/C LTE/EPC r14.9.0 v6.3.0

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

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

Converts an encoded PDU to XML.

Arguments

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

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

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

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

Errors and Warnings

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

Return Value

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


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

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

Arguments

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

Errors and Warnings

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

Return Value

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

Example

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

See Also

ossNASCpyValue()


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

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

Arguments

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

Errors and Warnings

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

Return Value

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

Example

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

See Also


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

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

Arguments

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

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

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

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

Determinant fields

Certain fields present in a NAS message play a special role in an encoding. Some of those special fields (e.g., 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:

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

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

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

Errors and Warnings

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

Return Value

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

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

Example

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

See Also


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

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

Arguments

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

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

Return Value

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

Example

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

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

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

Arguments

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

Errors and Warnings

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

Return Value

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

Example

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

See Also

ossNASEncode()


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

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

Arguments

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

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

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

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

Determinant fields

Certain fields present in a NAS message play a special role in an encoding. Some of those special fields (e.g., 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:

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

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

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

Read-only fields

Certain fields present in a NAS message are specified as read-only and their values are ignored by the encode operation. Those fields include most determinant fields as well as all the fields that are constrained by the 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 NAS1490.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 NAS1490__choice1 or NAS1490__choice2, respectively). The value of the messageType field is ignored by the ossNASEncode() function.

Errors and Warnings

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

Return Value

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

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

Example

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

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

See Also


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

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

Arguments

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

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

Return Value

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

Example

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

Refer to the Example section to see a complete example.

See Also

ossNASFreePDU()


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

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

Arguments

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

Return Value

The ossNASFreeMemory() function does not return a value.

Example

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

See Also

ossNASGetMemory()


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

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

Arguments

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

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

Return Value

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

Example

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

Refer to the Example section to see a complete example.

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

See Also

ossNASFreeBuf()


unsigned long ossNASGetDecodingFlags(OssNASGlobal *world);

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

Arguments

world
Pointer to the global OSS NAS environmental variable.

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

Return Value

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

Example

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

See Also


long ossNASGetDecodingLength(OssNASGlobal *world);

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

Arguments

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

Return Value

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

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

Example

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

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

See Also


long ossNASGetFinalDecodingLength(OssNASGlobal *world);

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

Arguments

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

Return Value

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

Example

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

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

See Also

ossNASSetDecodingLength()


unsigned long ossNASGetEncodingFlags(OssNASGlobal *world);

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

Arguments

world
Pointer to the global OSS NAS environmental variable.

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

Return Value

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

Example

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

See Also


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

Retrieves information about 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.

Arguments

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

This function fills the above output structure as follows:

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

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

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

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

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

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

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

Return Value

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

Example

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

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

See Also


char *ossNASGetErrMsg(OssNASGlobal *world);

Retrieves 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.

Arguments

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

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

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

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

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

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

Return Value

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

Example

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

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

See Also


unsigned long ossNASGetFlags(OssNASGlobal *world);

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

Arguments

world
Pointer to the global OSS NAS environmental variable.

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

Return Value

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

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

Example

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

See Also


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

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

Arguments

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

Return Value

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

See Also

ossNASFreeMemory()


unsigned long ossNASGetOriginator(OssNASGlobal *world);

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

Arguments

world
Pointer to the global OSS NAS environmental variable.

Return Value

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

Example

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

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

See Also

ossNASSetOriginator().


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

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

Arguments

world
Pointer to the global OSS NAS environmental variable.
NASversion
A character string specifying a version of 3GPP NAS. To use 3GPP v14.9.0 specify "NAS1490" as the second argument of this function.

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

If 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.

Return Value

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

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

Example 1

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

Refer to the Example section to see a complete example.

Example 2

OssNASGlobal wNAS1280, *worldNAS1280 = &wNAS1280;
OssNASGlobal wNAS1490, *worldNAS1490 = &wNAS1490;
. . . .
ossNASinit(worldNAS1280, "NAS1280");
ossNASinit(worldNAS1490, "NAS1490");

/* use world1280 to work with NAS 12.8.0 messages */
/* use world1490 to work with NAS 14.9.0 messages */

ossNASterm(worldNAS1280);
ossNASterm(worldNAS1490);

See Also

ossNASterm()


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

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

Arguments

world
Pointer to the global OSS NAS environmental variable.

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

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

Return Value

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

Example

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

See Also

ossNASPrintPDU()


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

Allows printing of values in variables of type NAS1490_NASMessage (defined in the NAS1490.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.

Arguments

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

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

Errors and Warnings

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

Return Value

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

Example

OssNASGlobal w, *world = &w;
OssBuf encodedData;
int pdunum = OSSNAS_PDUNUM;
NAS1490_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>

See Also

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

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

Arguments

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

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

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

Return Value

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

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

Example

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

See Also


int ossNASSetDecodingLength(OssNASGlobal *world, long bufferLength);

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

Arguments

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

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

Return Value

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

Example

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

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

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

See Also

ossNASGetDecodingLength()


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

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

Arguments

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

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

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

Return Value

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

Example

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

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

See Also


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

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

Arguments

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

The OSSNAS_IGNORECEFCONSTRAINTS flag relaxes some constraints while encoding and decoding. Some optional Information Elements in NAS messages that are not syntactically correct could still be successfully decoded when this flag is set. 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.

Return Value

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

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

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

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

Example

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

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

See Also


int ossNASSetOriginator(OssNASGlobal *world, int originator);

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

Arguments

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

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

Return Value

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

Example

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

See Also

ossNASGetOriginator()


void ossNASterm(OssNASGlobal *world);

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

Arguments

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

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

Return Value

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

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

Example

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

Refer to the Example section to see a complete example.

See Also

ossNASinit()


This documentation applies to the OSS NAS Tools for C for LTE/EPC v6.3.0 for 3GPP Release 14.9.0.

Copyright © 2020 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.