Core Endian Reference

Framework
CoreServices/CoreServices.h
Declared in
Endian.h

Overview

Core Endian Reference provides routines for converting data between big endian and little endian format. These routines are useful for developers who write code that must compile for multiple architectures, including:

Both QuickTime and Macintosh developers can use this API to handle reading or writing data to a file or network packet.

Macintosh developers can use this API to create and install callbacks that are invoked by OS X automatically when your application:

The functions in this API are designed to do nothing when the target runtime is already in the desired format.

For more information see:

Functions by Task

Working With Flippers

Changing the Endian Format

Converting from Big-Endian to Native Format

Converting from Native Format to Big-Endian Format

Converting from Little-Endian Format to Native Format

Converting from Native Format to Little-Endian Format

Converting from Big-Endian to Little-Endian Format

Converting From Little-Endian to Big-Endian Format

Callbacks

CoreEndianFlipProc

Defines a pointer to a callback function that byte-swaps your custom data.

typedef CALLBACK_API (OSStatus, CoreEndianFlipProc)
   (OSType dataDomain,
   OSType dataType,
   short id,
   void *dataPtr,
   UInt32 dataSize,
   Boolean currentlyNative,
   void *refcon
);

You would declare your flipper callback function as follows if your were to name it MyCoreEndianFlipProc:

OSStatus MyCoreEndianFlipProc (
   OSType dataDomain,
   OSType dataType,
   short id,
   void *dataPtr,
   UInt32 dataSize,
   Boolean currentlyNative,
   void *refcon
);

Parameters
dataDomain

An OSType value that specifies the domain to which the flipper callback applies. The value kCoreEndianResourceManagerDomain signifies the domain is resource data. The value kCoreEndianAppleEventManagerDomain signifies the domain is Apple event data. See “Domain Types” for more information on the values that can be passed to your callback.

dataType

The type of data to be byte swapped by the callback. This is the four character code of the resource type or Apple event.

id

The resource id of the data type. The value 0 signifies the data is not a resource.

dataPtr

On input, points to the data to be flipped. On output, points to the byte-swapped data.

dataSize

The size of the data pointed to the by the dataPtr parameter.

currentlyNative

A Boolean value that indicates the direction to byte swap. The value true specifies the data pointed to by the dataPtr parameter uses the byte ordering of the currently executing code. On a PowerPC system, true specifies that the data is in big-endian format. On an x86 system, true specifies that the data is in little-endian format.

refcon

A 32-bit value that contains or refers to data needed by the callback.

Return Value

A result code that indicates whether the byte swapping is successful. Your callback should return noErr if the resource is byte swapped without error, handlerNotFound if you chose not to byte swap the data, and the appropriate result code to indicate an error condition if the data is bad. The result code you return is propagated through the appropriate manager (Resource Manager (ResError) or Apple Event Manager) to the caller.

Discussion

You should write each flipper callback so it traverses the data structure that contains the data and performs the following tasks:

  • Byte swaps all Resource Manager counts and lengths so that array indexes are associated with the appropriate value

  • Byte swaps all integers and longs so that when you read them into variables of a compatible type the values can be operated on correctly (such as numerical, offset, and shift operations)

A flipper callback must be bidirectional because it can be called by the Resource Manager or Apple Event Manager when you read data as well as when you write data. The system ensures that your flipper callback is invoked at the appropriate times.

Your flipper callback is not invoked on a microprocessor that uses big-endian byte ordering. It is called with currentlyNative set to false when data is read (or received) and true when the data is set to be written (or sent).

Availability
  • Deprecated in OS X v10.8.
Declared In
Endian.h

Data Types

BigEndianLong

Protects a big-endian long value from being changed by little-endian code.

// Little-endian host
struct BigEndianLong {
   long bigEndianValue;
};
typedef struct BigEndianLong  BigEndianLong;
   // Big-endian host
   typedef long  BigEndianLong;
Fields
bigEndianValue

A long value.

Availability
  • Available in OS X v10.0 and later.
Declared In
Endian.h

BigEndianUnsignedLong

Protects a big-endian unsigned long value from being changed by little-endian code.

// Little-endian host
struct BigEndianUnsignedLong {
   unsigned long    bigEndianValue;
};
typedef struct BigEndianUnsignedLong BigEndianUnsignedLong;
   // Big-endian host
   typedef unsigned long  BigEndianUnsignedLong;
Fields
bigEndianValue

An unsigned long value.

Availability
  • Available in OS X v10.0 and later.
Declared In
Endian.h

BigEndianShort

Protects a big-endian short value from being changed by little-endian code.

// Little-endian host
struct BigEndianShort {
   short    bigEndianValue;
};
typedef struct BigEndianShort  BigEndianShort;
   // Big-endian host
   typedef short BigEndianShort;
Fields
bigEndianValue

A short value.

Availability
  • Available in OS X v10.0 and later.
Declared In
Endian.h

BigEndianUnsignedShort

Protects a big-endian unsigned short value from being changed by little-endian code.

// Little-endian host
struct BigEndianUnsignedShort {
   unsigned short    bigEndianValue;
};
typedef struct BigEndianUnsignedShort  BigEndianUnsignedShort;
   // Big-endian host
   typedef unsigned short BigEndianUnsignedShort;
Fields
bigEndianValue

An unsigned short value.

Availability
  • Available in OS X v10.0 and later.
Declared In
Endian.h

BigEndianFixed

Protects a big-endian Fixed value from being changed by little-endian code.

// Little-endian host
struct BigEndianFixed {
   Fixed    bigEndianValue;
};
typedef struct BigEndianFixed  BigEndianFixed;
   // Big-endian host
   typedef Fixed BigEndianFixed;
Fields
bigEndianValue

A fixed value.

Availability
  • Available in OS X v10.0 and later.
Declared In
Endian.h

BigEndianUnsignedFixed

Protects a big-endian unsigned Fixed value from being changed by little-endian code.

// Little-endian host
struct BigEndianUnsignedFixed {
   UnsignedFixed    bigEndianValue;
};
typedef struct BigEndianUnsignedFixed  BigEndianUnsignedFixed;
   // Big-endian host
   typedef UnsignedFixed BigEndianUnsignedFixed;
Fields
bigEndianValue

An unsigned fixed value.

Availability
  • Available in OS X v10.0 and later.
Declared In
Endian.h

BigEndianOSType

Protects a big-endian OSType value from being changed by little-endian code.

// Little-endian host
struct BigEndianOSType {
   OSType    bigEndianValue;
};
typedef struct BigEndianOStype  BigEndianOStype;
   // Big-endian host
   typedef OSType BigEndianOSType;
Fields
bigEndianValue

An OSType value.

Availability
  • Available in OS X v10.0 and later.

Constants

Domain Types

Specify the domain to which a flipper callback should be applied.

enum {
   kCoreEndianResourceManagerDomain = 'rsrc',
   kCoreEndianAppleEventManagerDomain = 'aevt'
};
Constants
kCoreEndianResourceManagerDomain

Specifies that the domain is limited to the resources for a specific application.

Available in OS X v10.4 and later.

Declared in Endian.h.

kCoreEndianAppleEventManagerDomain

Specifies that the domain is limited to Apple events.

Available in OS X v10.4 and later.

Declared in Endian.h.

Discussion

The data types have specific meanings within their domain, although some data types can be registered with the same callback in several domains.

Availability
  • Available in OS X v10.3 and later.


© 2005, 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-23)

Did this document help you? Yes It's good, but... Not helpful...