TOP

Overview

Applies to: NAS/C LTE/EPC r15.8.0 v7.2.0

General Overview

The OSS NAS/C encoder transforms data stored in C data structures into an encoded NAS protocol data unit. The decoder performs the inverse operation, transforming an encoded NAS protocol data unit into C data structures.

To use the API functions, include the provided C header files and explicitly link your application with the OSS NAS import library, "ossNAS.lib".

Common Characteristics among OSS NAS/C API Functions

A typical OSS NAS/C API function prototype looks like:

returnType ossNASFunctionName(OssNASGlobal *world, type1 arg1, ..., typen, argn);

Note that all OSS NAS/C API functions begin with the ossNAS prefix and most take a pointer to an instance of the OssNASGlobal structure as their first argument. This structure contains information about the OSS NAS runtime environment that needs to be retained from one call to an OSS NAS/C API function to the next. Following this global environment variable, one or more additional arguments may be present. Finally, an OSS NAS/C API function may return a value or may not.

Calling the OSS NAS/C API Functions

Before calling an OSS NAS/C API function, the user has to declare and initialize a global environment variable of type OssNASGlobal. This initialization is done using the ossNASinit() function. The code for this procedure typically looks like:

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

Note: If you plan to use multiple simultaneous threads, you should keep a separate unshared instance of the OssNASGlobal structure for each thread.

Once the OssNASGlobal structure has been initialized, you may call any of the provided API functions passing the initialized OssNASGlobal variable as a first argument. For example:

ossNASPrint(world, "Hello world.\n");

After finishing all other calls to the OSS NAS/C API functions, your application should free up the allocated PDUs and encoder buffers using the ossNASFreePDU() and ossNASFreeBuf() functions, respectively. Then, your application should call the terminating function ossNASterm() to free the allocated OssNASGlobal structures and wrap up the use of the OSS NAS/C API functions.

Errors and Warnings

The following OSS NAS/C API functions can generate multiple error messages and warning messages during a single invocation of the function:

When an encode or decode error or other unexpected situation occurs during the execution of an encode or decode operation performed internally by those functions, the operation generates a severe error condition, a recoverable error condition, or a warning condition.

A severe error condition is generated when the encode or decode operation either cannot continue or would produce a meaningless result if it did. When a severe error condition occurs, the operation terminates immediately and is considered failed. Some examples of severe error conditions are: an output buffer that is too small to contain the output data; a choice index that is out of range; a mandatory IE that is missing; an unknown IE that has "comprehension required".

A recoverable error condition is generated when the operation can continue safely but will have to be considered failed when it terminates. Eventually, the operation will terminate either when it reaches its completion or because of a severe error condition. In either case, the operation will be considered failed. Some examples of recoverable error conditions are: a field that is required by the specification to have a fixed value but does not have that value; a field that is required by the specification not to have certain values but has one of those values.

A warning condition is generated when the operation can continue safely and it does not, by itself, require that the operation be considered failed when it terminates. Eventually, the operation will terminate either when it reaches its completion or because of a severe error condition. If no severe or recoverable error conditions occur during the operation, the operation will be considered successful regardless of any warning conditions occurred.

In decode operations, there are many unexpected situations that will generate a severe or recoverable error condition when they occur in a mandatory part of a message or inside an optional IE with "comprehension required" but will generate a warning condition when they occur inside an optional IE without "comprehension required". In the latter case, the invalid optional IE is treated as if it were not part of the input (the encoded message), and will be marked as absent in the output (the decoded message). Eventually, the decode operation will be considered successful unless a severe or recoverable error condition occurs.

When an error or warning condition occurs, the OSS NAS/C API functions listed above produce an error or warning message. An error or warning message has the following format:

  1. A message code, formatted as follows:
    • One letter identifies the operation: E stands for "encode", D stands for "decode".
    • A four-digit number, 0001 to 9999, identifies the condition.
    • One letter indicates the severity: S stands for "severe error", E stands for "recoverable error", W stands for "warning.
    • A colon (:) and a space.
  2. A textual description of the condition (US-ASCII character string), followed by a semicolon (;) and a space.
  3. The word check.
  4. The path of the field in which or after which the condition occurred, formatted as follows: ( field ('ident' | #elem ) (type: basetype) of )* PDU 'pduname' where:
    • ident is the ASN.1 identifier of a component of a SEQUENCE or CHOICE type.
    • elem is the ordinal number of an element of a SEQUENCE OF type.
    • basetype is one of SEQUENCE, CHOICE, SEQUENCE OF.
    • pduname is the name of the PDU type (NASMessage) with spaces inserted between words.

Examples

D0065E: An unknown information element was detected in the encoded data; check field 'protocolConfigurationOptions' of field 'activateDefaultEPSBearerContextRequest' (type: SEQUENCE) of field 'body' (type: CHOICE) of field 'esmMessage' (type: SEQUENCE) of PDU 'NASMessage'
D0061W: A forbidden value was detected in the encoded data; check field 'systemIdentification' of field #2 (type: SEQUENCE) of field 'supportedCodecs' (type: SEQUENCE OF) of field 'attachRequest' (type: SEQUENCE) of field 'body' (type: CHOICE) of field 'plain' (type: SEQUENCE) of field 'emmMessage' (type: CHOICE) of PDU 'NASMessage'

The OSS NAS/C API functions utilize two distinct memory buffers—an error message buffer and a warning message buffer—to store the messages produced for the error and warning conditions occurring during one execution of the operation. Severe and recoverable error messages are added to the error message buffer; warning messages are added to the warning message buffer. In most practical cases, these buffers are large enough to contain all the error and warning messages produced by an operation, but in rare cases one or both buffers may become full. Usually this is not an issue, since a user application is rarely interested in all the error or warning messages produced by a single function call that has produced many such messages.

When a call to one of the functions listed above generates one or more severe or recoverable error conditions, it returns an integer different from zero, which is the code of the first severe or recoverable error condition that occurred during the operation. If you want to know details about the severe or recoverable error conditions that occurred, you can then call either the ossNASGetErrMsg() function or the ossNASGetErrInfo() function. The ossNASGetErrMsg() function returns a pointer to the error message buffer, allowing you to read the error messages generated by the operation. The ossNASGetErrInfo() function returns some more details, including a pointer to the warning message buffer. You can call the ossNASGetErrInfo() function even if the call to the encode or decode function was successful (return code 0), in case you want to know whether the operation generated any warnings and read the warning messages.


This documentation applies to the OSS NAS Tools for C for LTE/EPC v7.2.0 for 3GPP Release 15.8.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.