Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access Force Feedback Framework Reference

Overview

Constants used in the public interfaces to the Force Feedback implementation in Mac OS X.

Discussion

This header file contains the Effect type UUIDs, type definitions used in the API, force feedback constants and error values used by the API.

Typedefs

FFCapabilitiesEffectSubType

FFCapabilitiesEffectType

FFCommandFlag

FFCooperativeLevelFlag

FFCoordinateSystemFlag

FFEffectParameterFlag

FFEffectStartFlag

FFEffectStatusFlag

FFProperty

FFState

typedef UInt32 FFCapabilitiesEffectSubType;  

Discussion

Flags used to specify the subtype of an effect.

typedef UInt32 FFCapabilitiesEffectType;  

Discussion

Types used in the emulatedEffects or supportedEffects members of the FFCAPABILITIES structure. Used to describe whether the particular effect type is supported or emulated by the device.

typedef UInt32 FFCommandFlag;  

Discussion

Command flags for FFDeviceSendForceFeedbackCommand().

typedef UInt32 FFCooperativeLevelFlag;  

Discussion

flags for FFDeviceSetCooperativeLevel().

typedef UInt32 FFCoordinateSystemFlag;  

Discussion

Different coordinates used by the Force Feedback framework.

typedef UInt32 FFEffectParameterFlag;  

Discussion

Effect Parameter flags for use in calls to FFEffectGetParameters() and FFEffectSetParameters().

typedef UInt32 FFEffectStartFlag;  

Discussion

Effect Parameter flags for use in calls to FFEffectStart().

typedef UInt32 FFEffectStatusFlag;  

Discussion

Effect Parameter flags for use in calls to FFEffectGetEffectStatus().

typedef UInt32 FFProperty;  

Discussion

Used for FFDeviceGetForceFeedbackProperty() and FFDeviceSetForceFeedbackProperty().

typedef UInt32 FFState;  

Discussion

Device state flags returned by FFDeviceGetForceFeedbackState().

Enumerated Types

FFCapabilitiesEffectSubType

FFCapabilitiesEffectType

FFCommandFlag

FFCooperativeLevelFlag

FFCoordinateSystemFlag

FFEffectParameterFlag

FFEffectStartFlag

FFEffectStatusFlag

FFProperty

FFState

enum { 
    FFCAP_ST_KINESTHETIC = 1, 
    FFCAP_ST_VIBRATION = 2 
};  

Discussion

Flags used to specify the subtype of an effect.

enum { 
    FFCAP_ET_CONSTANTFORCE = 0x00000001UL, 
    FFCAP_ET_RAMPFORCE = 0x00000002UL, 
    FFCAP_ET_SQUARE = 0x00000004UL, 
    FFCAP_ET_SINE = 0x00000008UL, 
    FFCAP_ET_TRIANGLE = 0x00000010UL, 
    FFCAP_ET_SAWTOOTHUP = 0x00000020UL, 
    FFCAP_ET_SAWTOOTHDOWN = 0x00000040UL, 
    FFCAP_ET_SPRING = 0x00000080UL, 
    FFCAP_ET_DAMPER = 0x00000100UL, 
    FFCAP_ET_INERTIA = 0x00000200UL, 
    FFCAP_ET_FRICTION = 0x00000400UL, 
    FFCAP_ET_CUSTOMFORCE = 0x00000800UL 
};  

Constants

Discussion

Types used in the emulatedEffects or supportedEffects members of the FFCAPABILITIES structure. Used to describe whether the particular effect type is supported or emulated by the device.

enum { 
    FFSFFC_RESET = 0x00000001UL, 
    FFSFFC_STOPALL = 0x00000002UL, 
    FFSFFC_PAUSE = 0x00000004UL, 
    FFSFFC_CONTINUE = 0x00000008UL, 
    FFSFFC_SETACTUATORSON = 0x00000010UL, 
    FFSFFC_SETACTUATORSOFF = 0x00000020UL 
};  

Discussion

Command flags for FFDeviceSendForceFeedbackCommand().

enum { 
    FFSCL_EXCLUSIVE = 0x00000001UL, 
    FFSCL_NONEXCLUSIVE = 0x00000002UL, 
    FFSCL_FOREGROUND = 0x00000004UL, 
    FFSCL_BACKGROUND = 0x00000008UL 
};  

Discussion

flags for FFDeviceSetCooperativeLevel().

enum { 
    FFEFF_CARTESIAN = 0x00000010UL, 
    FFEFF_POLAR = 0x00000020UL, 
    FFEFF_SPHERICAL = 0x00000040UL 
};  

Constants

Discussion

Different coordinates used by the Force Feedback framework.

enum { 
    FFEP_DURATION = 0x00000001UL, 
    FFEP_SAMPLEPERIOD = 0x00000002UL, 
    FFEP_GAIN = 0x00000004UL, 
    FFEP_TRIGGERBUTTON = 0x00000008UL, 
    FFEP_TRIGGERREPEATINTERVAL = 0x00000010UL, 
    FFEP_AXES = 0x00000020UL, 
    FFEP_DIRECTION = 0x00000040UL, 
    FFEP_ENVELOPE = 0x00000080UL, 
    FFEP_TYPESPECIFICPARAMS = 0x00000100UL, 
    FFEP_STARTDELAY = 0x00000200UL, 
    FFEP_ALLPARAMS = 0x000003FFUL, 
    FFEP_START = 0x20000000UL, 
    FFEP_NORESTART = 0x40000000UL, 
    FFEP_NODOWNLOAD = 0x80000000UL, 
    FFEB_NOTRIGGER = 0xFFFFFFFFUL 
};  

Discussion

Effect Parameter flags for use in calls to FFEffectGetParameters() and FFEffectSetParameters().

enum { 
    FFES_SOLO = 0x00000001UL, 
    FFES_NODOWNLOAD = 0x80000000UL 
};  

Discussion

Effect Parameter flags for use in calls to FFEffectStart().

enum { 
    FFEGES_NOTPLAYING = 0x00000000UL, 
    FFEGES_PLAYING = 0x00000001UL, 
    FFEGES_EMULATED = 0x00000002UL 
};  

Discussion

Effect Parameter flags for use in calls to FFEffectGetEffectStatus().

enum { 
    FFPROP_FFGAIN = 1UL, 
    FFPROP_AUTOCENTER = 3UL 
};  

Discussion

Used for FFDeviceGetForceFeedbackProperty() and FFDeviceSetForceFeedbackProperty().

enum { 
    FFGFFS_EMPTY = 0x00000001UL, 
    FFGFFS_STOPPED = 0x00000002UL, 
    FFGFFS_PAUSED = 0x00000004UL, 
    FFGFFS_ACTUATORSON = 0x00000010UL, 
    FFGFFS_ACTUATORSOFF = 0x00000020UL, 
    FFGFFS_POWERON = 0x00000040UL, 
    FFGFFS_POWEROFF = 0x00000080UL, 
    FFGFFS_SAFETYSWITCHON = 0x00000100UL, 
    FFGFFS_SAFETYSWITCHOFF = 0x00000200UL, 
    FFGFFS_USERFFSWITCHON = 0x00000400UL, 
    FFGFFS_USERFFSWITCHOFF = 0x00000800UL, 
    FFGFFS_DEVICELOST = 0x80000000UL 
};  

Discussion

Device state flags returned by FFDeviceGetForceFeedbackState().

Macro Definitions

E_PENDING

FF_DEGREES

FF_DOWNLOADSKIPPED

FF_EFFECTRESTARTED

FF_FALSE

FF_FFNOMINALMAX

FF_INFINITE

FF_OK

FF_SECONDS

FF_TRUNCATED

FF_TRUNCATEDANDRESTARTED

FFEFF_OBJECTOFFSETS

FFERR_DEVICEFULL

FFERR_DEVICENOTREG

FFERR_DEVICEPAUSED

FFERR_DEVICERELEASED

FFERR_EFFECTPLAYING

FFERR_EFFECTTYPEMISMATCH

FFERR_EFFECTTYPENOTSUPPORTED

FFERR_GENERIC

FFERR_HASEFFECTS

FFERR_INCOMPLETEEFFECT

FFERR_INTERNAL

FFERR_INVALIDDOWNLOADID

FFERR_INVALIDPARAM

FFERR_MOREDATA

FFERR_NOINTERFACE

FFERR_NOTDOWNLOADED

FFERR_NOTINITIALIZED

FFERR_OUTOFMEMORY

FFERR_UNPLUGGED

FFERR_UNSUPPORTED

FFERR_UNSUPPORTEDAXIS

FFJOFS_i

FFJOFS_X

kFFEffectType_ConstantForce_ID

kFFEffectType_CustomForce_ID

kFFEffectType_Damper_ID

kFFEffectType_Friction_ID

kFFEffectType_Inertia_ID

kFFEffectType_RampForce_ID

kFFEffectType_SawtoothDown_ID

kFFEffectType_SawtoothUp_ID

kFFEffectType_Sine_ID

kFFEffectType_Sine_ID

kFFEffectType_Spring_ID

kFFEffectType_Square_ID

kFFEffectType_Triangle_ID

#define E_PENDING 0x8000000AL 

Discussion

Data is not yet available.

#define FF_DEGREES 100 

#define FF_DOWNLOADSKIPPED  

Discussion

The parameters of the effect were successfully updated by FFEffectSetParameters, but the effect was not downloaded because the FFEP_NODOWNLOAD flag was passed.

#define FF_EFFECTRESTARTED  

Discussion

The parameters of the effect were successfully updated by FFEffectSetParameters, but in order to change the parameters, the effect needed to be restarted.

#define FF_FALSE S_FALSE 

Discussion

The operation did not complete successfully.

#define FF_FFNOMINALMAX 10000 

#define FF_INFINITE 0xFFFFFFFFUL 

#define FF_OK S_OK 

Discussion

The operation completed successfully.

#define FF_SECONDS 1000000 

#define FF_TRUNCATED  

Discussion

The parameters of the effect were successfully updated by FFEffectSetParameters, but some of them were beyond the capabilities of the device and were truncated.

#define FF_TRUNCATEDANDRESTARTED  

Discussion

Equal to FF_EFFECTRESTARTED | FF_TRUNCATED.

#define FFEFF_OBJECTOFFSETS 0x00000002UL 

Discussion

OBJECT IDS cannot be used to identify trigger buttons in FFEFFECT.dwTriggerButton, and output axes in FFEFFECT.rgdwAxes[n]. Please use object offsets (FFJOFS_* constants), the only supported method.

#define FFERR_DEVICEFULL 0x80040201L 

Discussion

The device is full.

#define FFERR_DEVICENOTREG REGDB_E_CLASSNOTREG 

Discussion

The device or device instance or effect is not registered.

#define FFERR_DEVICEPAUSED 0x80040301L 

Discussion

When the device is paused via a call to FFDeviceSendForceFeedbackCommand(), other operations such as modifying existing effect parameters and creating new effects are not allowed.

#define FFERR_DEVICERELEASED 0x80040307L 

Discussion

The device has been released.

#define FFERR_EFFECTPLAYING 0x80040208L 

Discussion

An attempt was made to modify parameters of an effect while it is playing. Not all hardware devices support altering the parameters of an effect while it is playing.

#define FFERR_EFFECTTYPEMISMATCH 0x80040303L 

Discussion

The IOForceFededbackLib driver has received an effect modification request whose basic type does not match the defined effect type for the given effect.

#define FFERR_EFFECTTYPENOTSUPPORTED 0x80040306L 

Discussion

The effect type requested is not explicitly supported by the particular device.

#define FFERR_GENERIC E_FAIL 

Discussion

An undetermined error occurred.

#define FFERR_HASEFFECTS 0x80040204L 

Discussion

The device cannot be reinitialized because there are still effects attached to it.

#define FFERR_INCOMPLETEEFFECT 0x80040206L 

Discussion

The effect could not be downloaded because essential information is missing. For example, no axes have been associated with the effect, or no type-specific information has been created.

#define FFERR_INTERNAL 0x80040302L 

Discussion

The IOForceFededbackLib driver has detected an internal fault. Often this occurs because of an unexpected internal code path.

#define FFERR_INVALIDDOWNLOADID 0x80040300L 

Discussion

The effect index provided by the API in downloadID is not recognized by the IOForceFeedbackLib driver.

#define FFERR_INVALIDPARAM E_INVALIDARG 

Discussion

An invalid parameter was passed to the returning function, or the object was not in a state that admitted the function to be called.

#define FFERR_MOREDATA 0x80040202L 

Discussion

Not all the requested information fit into the buffer.

#define FFERR_NOINTERFACE E_NOINTERFACE 

Discussion

The specified interface is not supported by the object

#define FFERR_NOTDOWNLOADED 0x80040203L 

Discussion

The effect is not downloaded.

#define FFERR_NOTINITIALIZED 0x80040305L 

Discussion

This object has not been initialized

#define FFERR_OUTOFMEMORY E_OUTOFMEMORY 

Discussion

Couldn't allocate sufficient memory to complete the caller's request.

#define FFERR_UNPLUGGED 0x80040209L 

Discussion

The operation could not be completed because the device is not plugged in.

#define FFERR_UNSUPPORTED E_NOTIMPL 

Discussion

The function called is not supported at this time

#define FFERR_UNSUPPORTEDAXIS 0x80040304L 

Discussion

The effect includes one or more axes that the device does not support.

#define FFJOFS_X 0 

Discussion

Axis and Button field offsets, used in FFEFFECT.dwTriggerButton and FFEFFECT.rgdwAxes[n].

#define FFJOFS_X 0 

Discussion

Axis and Button field offsets, used in FFEFFECT.dwTriggerButton and FFEFFECT.rgdwAxes[n].

#define kFFEffectType_ConstantForce_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x60, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a constant force effect type

#define kFFEffectType_CustomForce_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x6B, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a custom force effect type

#define kFFEffectType_Damper_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x68, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a damper effect type

#define kFFEffectType_Friction_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x6A, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a friction effect type

#define kFFEffectType_Inertia_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x69, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for an inertia effect type

#define kFFEffectType_RampForce_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x61, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a ramp force effect type

#define kFFEffectType_SawtoothDown_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x66, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a downwards sawtooth wave effect type

#define kFFEffectType_SawtoothUp_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x65, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a upwards sawtooth wave effect type

#define kFFEffectType_Sine_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x63, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a sine wave effect type

#define kFFEffectType_Triangle_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x64, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a sine wave effect type

#define kFFEffectType_Spring_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x67, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a spring effect type

#define kFFEffectType_Square_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x62, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a square wave effect type

#define kFFEffectType_Triangle_ID CFUUIDGetConstantUUIDWithBytes(NULL, \ 
    0xE5, 0x59, 0xC4, 0x64, 0xC5, 0xCD, 0x11, 0xD6, \ 
    0x8A, 0x1C, 0x00, 0x03, 0x93, 0x53, 0xBD, 0x00) 

Discussion

UUID for a sine wave effect type