Studio:Scl ptr

The scl_ptr pragma

The scl_ptr pragma is used to identify a pointer data type and assign it pointer-specific attributes, such as marshaling direction and memory usage.

Syntax

#pragma scl_ptr(type-name, direction, pointer-usage)

#pragma scl_ptr(type-name, field-name, direction, pointer-usage)

Parameters	Type	Description
type-name	Type	Name of the type that contains the pointer. The container type can be a structure, union, the pointer type itself, or a function. If the container type is a structure or union, the pointer is a member and the field-name must be specified. If the container type is a function, then the pointer is a parameter and the field-name must be specified.
field-name [Optional]	Member	Name of the pointer field, which may be a member field contained within a structure/union, or a parameter in the ParameterList of a function.
direction	Constant	Direction in which the pointer data is marshaled; refer to the Pointer Direction Table below. This affects read and write access to the pointer data.
pointer-usage	Constant	Pointer usage indicator; refer to the Pointer Memory Usage Table below.

Pointer Direction Table

Value	Meaning
IN	Specifies that the pointer memory can be used only as input to the receiver of the pointer. The Owner of the interface may only consider this read-only memory.
OUT	Specifies that the pointer memory can be used to output information. The memory is allocated by the User and only written to by the Owner.
INOUT	Specifies that the pointer memory can be used as both input and output. The User may send in data when sending the command (or calling the function), and may read the Owner’s output upon receipt of the response (or return of the function).
RETURN	Specifies that the pointer memory may be read by the User of the interface. The User may only consider this as read-only memory and must not free it.
INRETURN

Pointer Memory Usage Table

Value	Meaning
PRIVATE	Pointer memory is private and may not be released by the Reader.
POOL	Pointer memory is created from common pool and must be released by the Reader.

Notes

• A compiler error will be reported if an embedded pointer does not point to a fixed size type.
• Sized pointers cannot use the INOUT direction.
• Response payloads cannot use the OUT or INOUT direction.
• Pointers with OUT or INOUT direction cannot indicate POOL pointer usage.
• If the sized pointer is IN, then size-field-name can be a non-pointer integer type; otherwise it must be a single embedded pointer. In either case, the parameter size-field-name must have the same direction as its associated-sized pointer.
• One-way messages (command and response) cannot have data that contains an OUT or INOUT Pointer.
• Currently, the type of the data that is pointed to cannot be void; e.g., void *. This is considered an opaque pointer.
• For additional information on scl_ptr, including constraints, refer to the section on scl_ptr in the SCL Reference Guide].

Examples

Two examples using the scl_ptr pragma are shown below:

1. The first example uses the scl_ptr pragma to assign pointer attributes to a structure member and a parameter list member.
2. The second example uses the scl_ptr pragma to assign pointer attributes to type definitions.

Example 1

   /* Typedef defining a structure with a member of type pointer to char */
   typedef struct
   {
      int f1;
      char * f2;
   }data_t;

   /* Function prototype with an INOUT pointer of type data_t */
   void modifyData( data_t * p );

   /* Use the scl_function pragma to associate a SUID with the function ModifyData */
   #pragma scl_function( modifyData )
   /* Use the scl_ptr pragma to define the member f2 as a RETURN pointer */
   #pragma scl_ptr( data_t.f2, OUT, PRIVATE )
   /* Use the scl_ptr pragma to define the parameter p as an INOUT pointer */
   #pragma scl_ptr( modifyData.p, INOUT, PRIVATE ) 

Example 2

   /* Typedef defining a pointer as a status type */
   typedef int * StatusCode;
   /* Apply scl_ptr to the StatusCode type. It is always an OUT pointer type */
   #pragma scl_ptr ( StatusCode, OUT, PRIVATE );
   /* Prototype defining a function that returns a pointer to the data structure */
   void GetStatus( StatusCode outCode );
   /* Mark getStatus as an SCL-compliant function */
   #pragma scl_function ( GetStatus );