Hardware Effects
[System]


Data Structures

struct  _AlpHwEffectsNote

Stock Vibration/LED Patterns

These constants can be used as the url arguments to alp_hweffects_play() and alp_hweffects_play_for_duration(), to specify a system-defined pattern.

#define ALP_HWEFFECTS_ALARM_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "alarm"
#define ALP_HWEFFECTS_CONFIRM_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "confirm"
#define ALP_HWEFFECTS_CONNECT_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "connect"
#define ALP_HWEFFECTS_DIALPAD_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "dialpad"
#define ALP_HWEFFECTS_DISCONNECT_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "disconnect"
#define ALP_HWEFFECTS_GENERIC_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "etc"
#define ALP_HWEFFECTS_INCOMING_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "incoming"
#define ALP_HWEFFECTS_MESSAGE_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "message"
#define ALP_HWEFFECTS_NORMAL_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "normal"
#define ALP_HWEFFECTS_POPUP_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "popup"
#define ALP_HWEFFECTS_POWER_OFF_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "power_off"
#define ALP_HWEFFECTS_POWER_ON_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "power_on"
#define ALP_HWEFFECTS_SCROLL_RELEASE   ALP_HWEFFECTS_STOCK_PREFIX "scroll_end"
#define ALP_HWEFFECTS_SCROLL_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "scroll"
#define ALP_HWEFFECTS_SOFT_KEYPAD_RELEASE   ALP_HWEFFECTS_STOCK_PREFIX "keypad_release"
#define ALP_HWEFFECTS_SOFT_KEYPAD_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "soft_keypad"
#define ALP_HWEFFECTS_SOLID_PATTERN   ALP_HWEFFECTS_STOCK_PREFIX "solid"
#define ALP_HWEFFECTS_STOCK_PREFIX   "stock:effect/"
#define ALP_HWEFFECTS_SYSTEM_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "system"

Hardware Device Names

These constants can be used as the name arguments to alp_power_set_default_timeout() and alp_power_set_brightness(), to specify the backlight device(s) to which the new timeout/brightness setting should be applied.

#define ALP_HWEFFECTS_ATTN_LED   "_attn-led"
 LED(s) used to get user's attention.
#define ALP_HWEFFECTS_POWER_LED   "_power-led"
 LED(s) used to report power status.
#define ALP_HWEFFECTS_VIBRATOR   "_vibrator"
 Vibrator.

"Song" APIs

These APIs are used to compose and play "songs" (series of notes) on a device's LEDs and/or vibrator.

#define ALP_HWEFFECTS_COLOR_FADE(r1, g1, b1, r2, g2, b2, totalBeats)
#define ALP_HWEFFECTS_COLOR_FLASH(r, g, b, pattern, numSlots)
 Macro for formatting notes.
#define ALP_HWEFFECTS_COLOR_NOTE(r, g, b, beats)
 Macro for formatting notes for color LEDs.
#define ALP_HWEFFECTS_DEFAULT_TEMPO   100
 Default tempo is 100ms per beat (10 beats per second).
#define ALP_HWEFFECTS_FADE(intensity1, intensity2, totalBeats)
#define ALP_HWEFFECTS_FLASH(intensity, pattern, numSlots)   ALP_HWEFFECTS_COLOR_FLASH(intensity, intensity, intensity, pattern, numSlots)
#define ALP_HWEFFECTS_NOTE(intensity, beats)   ALP_HWEFFECTS_COLOR_NOTE(intensity, intensity, intensity, beats)
 Macro for formatting notes for LEDs and/or vibrator.
#define ALP_HWEFFECTS_REST(beats)   ALP_HWEFFECTS_NOTE(0, beats)
 Macro for formatting notes.
typedef _AlpHwEffectsNote AlpHwEffectsNote
 Structure used to store a single note.
typedef _AlpHwEffectsSong AlpHwEffectsSong
 Data type used to store a song.
enum  { ALP_HWEFFECTS_NOTE_SIMPLE, ALP_HWEFFECTS_NOTE_FLASH, ALP_HWEFFECTS_NOTE_FADE }
alp_status_t alp_hweffects_play (const char *device, const char *url, int playCount)
 Play a stored vibration/LED pattern.
alp_status_t alp_hweffects_play_for_duration (const char *device, const char *url, int playMillis)
 Play a stored vibration/LED pattern for the specified duration, repeating as necessary.
alp_status_t alp_hweffects_song_add_notes (AlpHwEffectsSong *song, const AlpHwEffectsNote notes[], int noteCount)
 Add a string of notes to a song.
AlpHwEffectsSong * alp_hweffects_song_create ()
 Create a new song.
void alp_hweffects_song_destroy (AlpHwEffectsSong *song)
 Destroy a song.
int alp_hweffects_song_get_duration (const AlpHwEffectsSong *song)
 Retrieve song's duration, in beats.
int alp_hweffects_song_get_repeat (const AlpHwEffectsSong *song)
 Retrieve song's internal repeat value.
int alp_hweffects_song_get_tempo (const AlpHwEffectsSong *song)
 Retrieve song's beat duration.
alp_status_t alp_hweffects_song_play (const char *device, const AlpHwEffectsSong *song, int playCount)
 Play a song.
alp_status_t alp_hweffects_song_play_for_duration (const char *device, const AlpHwEffectsSong *song, int playMillis)
 Play a song for the specified duration, repeating as necessary.
alp_status_t alp_hweffects_song_set_repeat (AlpHwEffectsSong *song, int repeatCount)
 Set song's internal repeat value.
alp_status_t alp_hweffects_song_set_tempo (AlpHwEffectsSong *song, int millisPerBeat)
 Sets a song's beat duration.
alp_status_t alp_hweffects_stop (void)
 Stop a vibration/LED pattern which is currently playing.
alp_status_t alp_hweffects_vibrate (int millis)
 Utility function for pulsing device's vibrator.

Hardware Effects Error Codes

#define ALP_STATUS_HWEFFECTS_BAD_FORMAT   (ALP_CLASS_HWEFFECTS | 0x00060000)
 Invalid value in note data field.
#define ALP_STATUS_HWEFFECTS_DEVICE_BUSY   (ALP_CLASS_HWEFFECTS | 0x00070000)
 Song already playing on requested device.
#define ALP_STATUS_HWEFFECTS_INVALID_PARAM   (ALP_CLASS_HWEFFECTS | 0x00010000)
 Invalid parameter value.
#define ALP_STATUS_HWEFFECTS_NO_DEVICE   (ALP_CLASS_HWEFFECTS | 0x00050000)
 Specified device doesn't exist.
#define ALP_STATUS_HWEFFECTS_NO_FREE_RAM   (ALP_CLASS_HWEFFECTS | 0x00020000)
 Memory allocation failed.
#define ALP_STATUS_HWEFFECTS_NO_SERVER   (ALP_CLASS_HWEFFECTS | 0x00030000)
 Can't connect to HWeffects server.
#define ALP_STATUS_HWEFFECTS_NOT_ALLOWED   (ALP_CLASS_HWEFFECTS | 0x00040000)
 Operation not allowed.
#define ALP_STATUS_HWEFFECTS_NOT_PLAYING   (ALP_CLASS_HWEFFECTS | 0x00080000)
 Song not currently playing.

Define Documentation

#define ALP_HWEFFECTS_ALARM_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "alarm"
 

#define ALP_HWEFFECTS_ATTN_LED   "_attn-led"
 

LED(s) used to get user's attention.

#define ALP_HWEFFECTS_COLOR_FADE (  r1,
g1,
b1,
r2,
g2,
b2,
totalBeats   ) 
 

Value:

{ \
                .data1 = ((ALP_HWEFFECTS_NOTE_FADE << 30) \
                        | (((b1) & 0xffUL) << 16) \
                        | (((g1) & 0xffUL) << 8) \
                        | (((r1) & 0xffUL) << 0)), \
                .data2 = ((((b2) & 0xffUL) << 24) \
                        | (((g2) & 0xffUL) << 16) \
                        | (((r2) & 0xffUL) << 8) \
                        | ((totalBeats) & 0xffUL)), \
        }

#define ALP_HWEFFECTS_COLOR_FLASH (  r,
g,
b,
pattern,
numSlots   ) 
 

Value:

{ \
                .data1 = ((ALP_HWEFFECTS_NOTE_FLASH << 30) \
                        | (((numSlots) & 0x1fUL) << 24) \
                        | (((b) & 0xffUL) << 16) \
                        | (((g) & 0xffUL) << 8) \
                        | (((r) & 0xffUL) << 0)), \
                .data2 = (pattern), \
        }
Macro for formatting notes.

#define ALP_HWEFFECTS_COLOR_NOTE (  r,
g,
b,
beats   ) 
 

Value:

{ \
                .data1 = ((ALP_HWEFFECTS_NOTE_SIMPLE << 30) \
                        | (((b) & 0xffUL) << 16) \
                        | (((g) & 0xffUL) << 8)  \
                        | (((r) & 0xffUL) << 0)), \
                .data2 = ((beats) & 0xffUL), \
        }
Macro for formatting notes for color LEDs.

#define ALP_HWEFFECTS_CONFIRM_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "confirm"
 

#define ALP_HWEFFECTS_CONNECT_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "connect"
 

#define ALP_HWEFFECTS_DEFAULT_TEMPO   100
 

Default tempo is 100ms per beat (10 beats per second).

#define ALP_HWEFFECTS_DIALPAD_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "dialpad"
 

#define ALP_HWEFFECTS_DISCONNECT_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "disconnect"
 

#define ALP_HWEFFECTS_FADE (  intensity1,
intensity2,
totalBeats   ) 
 

Value:

ALP_HWEFFECTS_COLOR_FADE(intensity1, intensity1, intensity1, \
                                intensity2, intensity2, intensity2,totalBeats)

#define ALP_HWEFFECTS_FLASH (  intensity,
pattern,
numSlots   )     ALP_HWEFFECTS_COLOR_FLASH(intensity, intensity, intensity, pattern, numSlots)
 

#define ALP_HWEFFECTS_GENERIC_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "etc"
 

#define ALP_HWEFFECTS_INCOMING_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "incoming"
 

#define ALP_HWEFFECTS_MESSAGE_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "message"
 

#define ALP_HWEFFECTS_NORMAL_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "normal"
 

#define ALP_HWEFFECTS_NOTE (  intensity,
beats   )     ALP_HWEFFECTS_COLOR_NOTE(intensity, intensity, intensity, beats)
 

Macro for formatting notes for LEDs and/or vibrator.

#define ALP_HWEFFECTS_POPUP_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "popup"
 

#define ALP_HWEFFECTS_POWER_LED   "_power-led"
 

LED(s) used to report power status.

#define ALP_HWEFFECTS_POWER_OFF_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "power_off"
 

#define ALP_HWEFFECTS_POWER_ON_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "power_on"
 

#define ALP_HWEFFECTS_REST (  beats   )     ALP_HWEFFECTS_NOTE(0, beats)
 

Macro for formatting notes.

#define ALP_HWEFFECTS_SCROLL_RELEASE   ALP_HWEFFECTS_STOCK_PREFIX "scroll_end"
 

#define ALP_HWEFFECTS_SCROLL_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "scroll"
 

#define ALP_HWEFFECTS_SOFT_KEYPAD_RELEASE   ALP_HWEFFECTS_STOCK_PREFIX "keypad_release"
 

#define ALP_HWEFFECTS_SOFT_KEYPAD_TOUCH   ALP_HWEFFECTS_STOCK_PREFIX "soft_keypad"
 

#define ALP_HWEFFECTS_SOLID_PATTERN   ALP_HWEFFECTS_STOCK_PREFIX "solid"
 

#define ALP_HWEFFECTS_STOCK_PREFIX   "stock:effect/"
 

#define ALP_HWEFFECTS_SYSTEM_ALERT   ALP_HWEFFECTS_STOCK_PREFIX "system"
 

#define ALP_HWEFFECTS_VIBRATOR   "_vibrator"
 

Vibrator.

#define ALP_STATUS_HWEFFECTS_BAD_FORMAT   (ALP_CLASS_HWEFFECTS | 0x00060000)
 

Invalid value in note data field.

#define ALP_STATUS_HWEFFECTS_DEVICE_BUSY   (ALP_CLASS_HWEFFECTS | 0x00070000)
 

Song already playing on requested device.

#define ALP_STATUS_HWEFFECTS_INVALID_PARAM   (ALP_CLASS_HWEFFECTS | 0x00010000)
 

Invalid parameter value.

#define ALP_STATUS_HWEFFECTS_NO_DEVICE   (ALP_CLASS_HWEFFECTS | 0x00050000)
 

Specified device doesn't exist.

#define ALP_STATUS_HWEFFECTS_NO_FREE_RAM   (ALP_CLASS_HWEFFECTS | 0x00020000)
 

Memory allocation failed.

#define ALP_STATUS_HWEFFECTS_NO_SERVER   (ALP_CLASS_HWEFFECTS | 0x00030000)
 

Can't connect to HWeffects server.

#define ALP_STATUS_HWEFFECTS_NOT_ALLOWED   (ALP_CLASS_HWEFFECTS | 0x00040000)
 

Operation not allowed.

#define ALP_STATUS_HWEFFECTS_NOT_PLAYING   (ALP_CLASS_HWEFFECTS | 0x00080000)
 

Song not currently playing.

Typedef Documentation

typedef struct _AlpHwEffectsNote AlpHwEffectsNote
 

Structure used to store a single note.

typedef struct _AlpHwEffectsSong AlpHwEffectsSong
 

Data type used to store a song.

Enumeration Type Documentation

anonymous enum
 

Enumerator:
ALP_HWEFFECTS_NOTE_SIMPLE 
ALP_HWEFFECTS_NOTE_FLASH 
ALP_HWEFFECTS_NOTE_FADE 

Function Documentation

alp_status_t alp_hweffects_play (  const char *  device,
const char *  url,
int  playCount
) 
 

Play a stored vibration/LED pattern.

Parameters:
[in] device,: the device from which the stored vibration/LED is played
[in] url,: Use one of the system Vibration/LED defined patterns
[in] playCount,: Number of times the pattern is played
Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_INVALID_PARAM Invalid input parameter

ALP_STATUS_HWEFFECTS_NO_FREE_RAM Memory allocation failed

alp_status_t alp_hweffects_play_for_duration (  const char *  device,
const char *  url,
int  playMillis
) 
 

Play a stored vibration/LED pattern for the specified duration, repeating as necessary.

Parameters:
[in] device,: the device from which the stored vibration/LED is played
[in] url,: Use one of the system Vibration/LED defined patterns
[in] playMillis,: The duration the pattern is played
Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_INVALID_PARAM Invalid input parameter

ALP_STATUS_HWEFFECTS_NO_FREE_RAM Memory allocation failed

alp_status_t alp_hweffects_song_add_notes (  AlpHwEffectsSong *  song,
const AlpHwEffectsNote  notes[],
int  noteCount
) 
 

Add a string of notes to a song.

Parameters:
[in] song,: A pointer to the song.
[in] notes,: Notes to be added.
[in] noteCount,: Number of notes.
Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_INVALID_PARAM Invalid input parameter

ALP_STATUS_HWEFFECTS_NOT_ALLOWED Operation not allowed

ALP_STATUS_HWEFFECTS_BAD_FORMAT Invalid value in note data field

AlpHwEffectsSong* alp_hweffects_song_create (   ) 
 

Create a new song.

Returns:
It returns a song that is ready for notes

void alp_hweffects_song_destroy (  AlpHwEffectsSong *  song  ) 
 

Destroy a song.

Parameters:
[in] *song,: A song that is already created

int alp_hweffects_song_get_duration (  const AlpHwEffectsSong *  song  ) 
 

Retrieve song's duration, in beats.

Parameters:
[in] song,: A pointer to the song.
Returns:
Song's duration in beats.

int alp_hweffects_song_get_repeat (  const AlpHwEffectsSong *  song  ) 
 

Retrieve song's internal repeat value.

Parameters:
[in] song,: A pointer to the song that is already created
Returns:
NULL: song is NULL

Song's repeat count in milliseconds.

int alp_hweffects_song_get_tempo (  const AlpHwEffectsSong *  song  ) 
 

Retrieve song's beat duration.

Parameters:
[in] song,: A pointer to the song that is already created
Returns:
NULL: song is NULL

Song's beat in milliseconds.

alp_status_t alp_hweffects_song_play (  const char *  device,
const AlpHwEffectsSong *  song,
int  playCount
) 
 

Play a song.

Parameters:
[in] device,: the device from which the song is played
[in] song,: A pointer to the song.
[in] playCount,: Number of times the song is played
Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_INVALID_PARAM Invalid input parameter

alp_status_t alp_hweffects_song_play_for_duration (  const char *  device,
const AlpHwEffectsSong *  song,
int  playMillis
) 
 

Play a song for the specified duration, repeating as necessary.

Parameters:
[in] device,: the device from which the song is played.
[in] song,: A pointer to the song.
[in] playMillis,: The duration the song is played.
Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_INVALID_PARAM Invalid input parameter

ALP_STATUS_HWEFFECTS_NO_FREE_RAM Memory allocation failed

alp_status_t alp_hweffects_song_set_repeat (  AlpHwEffectsSong *  song,
int  repeatCount
) 
 

Set song's internal repeat value.

Parameters:
[in] song,: A pointer to the song that is already created
[in] repeatCount,: Song's repeat count in milliseconds
Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_INVALID_PARAM Invalid input parameter

alp_status_t alp_hweffects_song_set_tempo (  AlpHwEffectsSong *  song,
int  millisPerBeat
) 
 

Sets a song's beat duration.

Parameters:
[in] song,: A pointer to the song that is already created
[in] millisPerBeat,: Song's beat in milliseconds
Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_INVALID_PARAM Invalid input parameter

ALP_STATUS_HWEFFECTS_NOT_ALLOWED Operation not allowed

alp_status_t alp_hweffects_stop (  void   ) 
 

Stop a vibration/LED pattern which is currently playing.

Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_NO_FREE_RAM Memory allocation failed

alp_status_t alp_hweffects_vibrate (  int  millis  ) 
 

Utility function for pulsing device's vibrator.

Parameters:
[in] millis,: The duration of the device's vibratation
Returns:
ALP_STATUS_OK success

ALP_STATUS_HWEFFECTS_INVALID_PARAM Invalid input parameter

ALP_STATUS_HWEFFECTS_NO_FREE_RAM Memory allocation failed

Generated on Wed Jul 30 07:06:42 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation

Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.