ADC Home > Reference Library > Reference > Carbon > Data Management > Core Endian Reference >

Next Page > Hide TOC

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 Mac 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

Functions

CoreEndianFlipData

Calls the flipper callback associated with the specified data type.

OSStatus CoreEndianFlipData (
   OSType dataDomain,
   OSType dataType,
   SInt16 id,
   void *data,
   ByteCount dataLen,
   Boolean currentlyNative
);

Parameters
dataDomain

An OSType value that specifies the domain of the flipper callback you want to invoke. Pass kCoreEndianResourceManagerDomain if your callback applies to resource data. Pass kCoreEndianAppleEventManagerDomain if your callback applies to Apple event data. See “Domain Types” for more information.

dataType

An OSType value that specifies the type of data that needs to be byte-swapped. This is the four character code of the resource type or Apple event. This never needs to be byte-swapped even though GDB and Xcode display the resource in byte-swapped order.

id

The resource ID of the data type. The Resource Manager byte-swaps this for you so you can compare the resource ID against constants in your code. If the data is not a resource, pass 0.

data

A pointer to the first byte of the data to be byte swapped.

dataLen

The length of the data (in bytes) to be byte swapped.

currentlyNative

A Boolean value that indicates the direction to byte swap. Pass true when the data specified by the data 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.

Return Value

A result code. Returns noErr if the data is byte swapped and handlerNotFound if the data is not byte swapped. Note that data is only byte swapped if it needs to be byte swapped.

Availability
Declared In
Endian.h

CoreEndianGetFlipper

Obtains the flipper callback that is installed for the specified data type.

OSStatus CoreEndianGetFlipper (
   OSType dataDomain,
   OSType dataType,
   CoreEndianFlipProc *proc,
   void **refcon
);

Parameters
dataDomain

An OSType value that specifies the domain of the flipper callback you want to obtain. Pass kCoreEndianResourceManagerDomain to obtain a callback that applies to resource data. Pass kCoreEndianAppleEventManagerDomain to obtain a callback that applies to Apple event data. See “Domain Types” for more information.

dataType

An OSType value that specifies the type of data associated with the flipper callback you want to obtain. This is the four character code of the resource type or Apple event. This never needs to be byte-swapped even though GDB and Xcode display the resource in byte-swapped order.

proc

On output, points to the flipper callback that is installed for the data type specified by the dataType parameter.

refCon

On output, points to a 32-bit value that references callback-specific data.

Return Value

A result code. Returns noErr if the flipper callback is found.

Discussion

You can call the function CoreEndianGetFlipper to determine whether a flipper for a given data type is available.

Availability
Declared In
Endian.h

CoreEndianInstallFlipper

Installs a flipper callback for the specified data type.

OSStatus CoreEndianInstallFlipper (
   OSType dataDomain,
   OSType dataType,
   CoreEndianFlipProc proc,
   void *refcon
);

Parameters
dataDomain

An OSType value that specifies the domain to which the flipper callback applies. Pass kCoreEndianResourceManagerDomain if your callback applies to resource data. Pass kCoreEndianAppleEventManagerDomain if your callback applies to Apple event data. See “Domain Types” for more information.

dataType

An OSType value that specifies the type of data for which you want your flipper callback installed. This is the four character code of the resource type or Apple event.

proc

A pointer to your flipper callback. The flipper callback is installed into a per-process table that is searched before the system table.

refCon

A 32-bit value containing or referring to data needed by the callback.

Return Value

A result code. Returns noErr if your flipper callback is installed.

Discussion

You should install the callback by calling the function CoreEndianInstallFlipper when your application calls its initialization routine or when you open your resource file.

Availability
Declared In
Endian.h

Endian16_Swap

Changes the endian format of an unsigned 16-bit integer.

UInt16 Endian16_Swap (
   UInt16    value
);

Parameters
value

An unsigned 16-bit integer input.

Return Value

The unsigned 16-bit integer result.

Availability
Declared In
Endian.h

Endian32_Swap

Changes the endian format of an unsigned 32-bit integer.

UInt32 Endian32_Swap (
   UInt32    value
);

Parameters
value

An unsigned 32-bit integer input.

Return Value

The unsigned 32-bit integer result.

Availability
Declared In
Endian.h

Endian64_Swap

Changes the endian format of an unsigned 64-bit integer.

static UInt64 Endian64_Swap (
   UInt64 value
);

Parameters
value

An unsigned 64-bit integer input.

Return Value

The unsigned 64-bit integer result.

Availability
Declared In
Endian.h

EndianS16_BtoL

Converts a signed 16-bit big-endian value to the equivalent little-endian value.

SInt16 EndianS16_BtoL (
   SInt16    value
);

Parameters
value

A signed 16-bit big-endian value.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianS16_BtoN

Converts a signed 16-bit big-endian value to the equivalent value in the computer’s native format.

SInt16 EndianS16_BtoN (
   SInt16    value
);

Parameters
value

A signed 16-bit big-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Related Sample Code
Declared In
Endian.h

EndianS16_LtoB

Converts a signed 16-bit little-endian value to the equivalent big-endian value.

SInt16 EndianS16_LtoB (
   SInt16    value
);

Parameters
value

A signed 16-bit little-endian value.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianS16_LtoN

Converts a signed 16-bit little-endian value to the equivalent value in the computer’s native format.

SInt16 EndianS16_LtoN (
   SInt16    value
);

Parameters
value

A signed 16-bit little-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianS16_NtoB

Converts a signed 16-bit value in the computer’s native format to the equivalent big-endian value.

SInt16 EndianS16_NtoB (
   SInt16    value
);

Parameters
value

A signed 16-bit value in the computer’s native format.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianS16_NtoL

Converts a signed 16-bit value in the computer’s native format to the equivalent little-endian value.

SInt16 EndianS16_NtoL (
   SInt16    value
);

Parameters
value

A signed 16-bit value in the computer’s native format.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianS32_BtoL

Converts a signed 32-bit big-endian value to the equivalent little-endian value.

SInt32 EndianS32_BtoL (
   SInt32    value
);

Parameters
value

A signed 32-bit big-endian value.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianS32_BtoN

Converts a signed 32-bit big-endian value to the equivalent value in the computer’s native format.

SInt32 EndianS32_BtoN (
   SInt32    value
);

Parameters
value

A signed 32-bit big-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianS32_LtoB

Converts a signed 32-bit little-endian value to the equivalent big-endian value.

SInt32 EndianS32_LtoB (
   SInt32    value
);

Parameters
value

A signed 32-bit little-endian value.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianS32_LtoN

Converts a signed 32-bit little-endian value to the equivalent value in the computer’s native format.

SInt32 EndianS32_LtoN (
   SInt32    value
);

Parameters
value

A signed 32-bit little-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianS32_NtoB

Converts a signed 32-bit value in the computer’s native format to the equivalent big-endian value.

SInt32 EndianS32_NtoB (
   SInt32    value
);

Parameters
value

A signed 32-bit value in the computer’s native format.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianS32_NtoL

Converts a signed 32-bit value in the computer’s native format to the equivalent little-endian value.

SInt32 EndianS32_NtoL (
   SInt32    value
);

Parameters
value

A signed 32-bit value in the computer’s native format.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianS64_BtoL

Converts a signed 64-bit big-endian value to the equivalent little-endian value.

SInt64 EndianS64_BtoL (
   SInt64    value
);

Parameters
value

A signed 64-bit big-endian value.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianS64_BtoN

Converts a signed 64-bit big-endian value to the equivalent value in the computer’s native format.

SInt64 EndianS64_BtoN (
   SInt64    value
);

Parameters
value

A signed 64-bit big-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianS64_LtoB

Converts a signed 64-bit little-endian value to the equivalent big-endian value.

SInt64 EndianS64_LtoB (
   SInt64    value
);

Parameters
value

A signed 64-bit little-endian value.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianS64_LtoN

Converts a signed 64-bit little-endian value to the equivalent value in the computer’s native format.

SInt64 EndianS64_LtoN (
   SInt64    value
);

Parameters
value

A signed 64-bit little-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianS64_NtoB

Converts a signed 64-bit value in the computer’s native format to the equivalent big-endian value.

SInt64 EndianS64_NtoB (
   SInt64    value
);

Parameters
value

A signed 64-bit value in the computer’s native format.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianS64_NtoL

Converts a signed 64-bit value in the computer’s native format to the equivalent little-endian value.

SInt64 EndianS64_NtoL (
   SInt64    value
);

Parameters
value

A signed 64-bit value in the computer’s native format.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianU16_BtoL

Converts an unsigned 16-bit big-endian value to the equivalent little-endian value.

UInt16 EndianU16_BtoL (
   UInt16    value
);

Parameters
value

An unsigned 16-bit big-endian value.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianU16_BtoN

Converts an unsigned 16-bit big-endian value to the equivalent value in the computer’s native format.

UInt16 EndianU16_BtoN (
   UInt16    value
);

Parameters
value

An unsigned 16-bit big-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianU16_LtoB

Converts an unsigned 16-bit little-endian value to the equivalent big-endian value.

UInt16 EndianU16_LtoB (
   UInt16    value
);

Parameters
value

An unsigned 16-bit little-endian value.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianU16_LtoN

Converts an unsigned 16-bit little-endian value to the equivalent value in the computer’s native format.

UInt16 EndianU16_LtoN (
   UInt16    value
);

Parameters
value

An unsigned 16-bit little-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianU16_NtoB

Converts an unsigned 16-bit value in the computer’s native format to the equivalent big-endian value.

UInt16 EndianU16_NtoB (
   UInt16    value
);

Parameters
value

An unsigned 16-bit value in the computer’s native format.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianU16_NtoL

Converts an unsigned 16-bit value in the computer’s native format to the equivalent little-endian value.

UInt16 EndianU16_NtoL (
   UInt16    value
);

Parameters
value

An unsigned 16-bit value in the computer’s native format.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianU32_BtoL

Converts an unsigned 32-bit big-endian value to the equivalent little-endian value.

UInt32 EndianU32_BtoL (
   UInt32    value
);

Parameters
value

An unsigned 32-bit big-endian value.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianU32_BtoN

Converts an unsigned 32-bit big-endian value to the equivalent value in the computer’s native format.

UInt32 EndianU32_BtoN (
   UInt32    value
);

Parameters
value

An unsigned 32-bit big-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianU32_LtoB

Converts an unsigned 32-bit little-endian value to the equivalent big-endian value.

UInt32 EndianU32_LtoB (
   UInt32    value
);

Parameters
value

An unsigned 32-bit little-endian value.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianU32_LtoN

Converts an unsigned 32-bit little-endian value to the equivalent value in the computer’s native format.

UInt32 EndianU32_LtoN (
   UInt32    value
);

Parameters
value

An unsigned 32-bit little-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianU32_NtoB

Converts an unsigned 32-bit value in the computer’s native format to the equivalent big-endian value.

UInt32 EndianU32_NtoB (
   UInt32    value
);

Parameters
value

An unsigned 32-bit value in the computer’s native format.

Return Value

The equivalent big-endian value.

Availability
Related Sample Code
Declared In
Endian.h

EndianU32_NtoL

Converts an unsigned 32-bit value in the computer’s native format to the equivalent little-endian value.

UInt32 EndianU32_NtoL (
   UInt32    value
);

Parameters
value

An unsigned 32-bit value in the computer’s native format.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianU64_BtoL

Converts an unsigned 64-bit big-endian value to the equivalent little-endian value.

UInt64 EndianU64_BtoL (
   UInt64    value
);

Parameters
value

An unsigned 64-bit big-endian value.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

EndianU64_BtoN

Converts an unsigned 64-bit big-endian value to the equivalent value in the computer’s native format.

UInt64 EndianU64_BtoN (
   UInt64    value
);

Parameters
value

An unsigned 64-bit big-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianU64_LtoB

Converts an unsigned 64-bit little-endian value to the equivalent big-endian value.

UInt64 EndianU64_LtoB (
   UInt64    value
);

Parameters
value

An unsigned 64-bit little-endian value.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianU64_LtoN

Converts an unsigned 64-bit little-endian value to the equivalent value in the computer’s native format.

UInt64 EndianU64_LtoN (
   UInt64    value
);

Parameters
value

An unsigned 64-bit little-endian value.

Return Value

The equivalent value in the computer’s native format.

Availability
Declared In
Endian.h

EndianU64_NtoB

Converts an unsigned 64-bit value in the computer’s native format to the equivalent big-endian value.

UInt64 EndianU64_NtoB (
   UInt64    value
);

Parameters
value

An unsigned 64-bit value in the computer’s native format.

Return Value

The equivalent big-endian value.

Availability
Declared In
Endian.h

EndianU64_NtoL

Converts an unsigned 64-bit value in the computer’s native format to the equivalent little-endian value.

UInt64 EndianU64_NtoL (
   UInt64    value
);

Parameters
value

An unsigned 64-bit value in the computer’s native format.

Return Value

The equivalent little-endian value.

Availability
Declared In
Endian.h

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:

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

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 Mac OS X v10.4 and later.

Declared in Endian.h.

kCoreEndianAppleEventManagerDomain

Specifies that the domain is limited to Apple events.

Available in Mac 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


Next Page > Hide TOC

© 2005, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-05-29)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.