KBDSetLedsAsyncEx

Syntax

#include <cafe/kbd.h>

typedef void (*KBDLedCallbackF) (KBDLedEvent* lev, void *cbArg);

KBDEc KBDSetLedsAsyncEx (KBDChannel ch, KBDLedState leds, KBDLedCallbackF fn, void *cbArg);

Parameters

ch Keyboard channel to set.
leds New KBDLedState to send to the keyboard.
fn Callback function pointer to call when command completes.
cbArg Argument for callback function called when command completes.

Return Values

KBDEc Keyboard error code.
KBD_SUCCESS if the call was successful.
KBD_ERR_NOT_INITIALIZED if the library was not initialized.
KBD_ERR_BAD_VALUE if ch or leds is out of range.
KBD_ERR_BUSY if unable to send an LED command to the keyboard.

Description

Sends an LED command to the keyboard on channel ch. The command instructs the keyboard to turn on the LEDs specified by leds.

KBDSetLedsAsyncEx is a non-blocking call, and it may be used from within a callback or whenever interrupts are disabled. This is in contrast to the blocking version of this function, KBDSetLedsEx.

The KBDSetLedsAsyncEx function sends a message to a lower-level driver to send the USB command. After the lower-level driver responds that it has tried to send the command, an interrupt callback occurs and the user-provided callback function is called with a return code and a user-provided argument. The rc returned in the callback is either KBD_SUCCESS or KBD_ERR_BUSY. This code must be checked to confirm that the LED command was successfully sent through the USB bus. The return code of the KBDSetLedsAsyncEx function must be checked to know if the request was sent to the lower-level driver.

Also, because this function sends a message over the USB bus, avoid calling it too frequently to avoid flooding the USB bus. Avoid sending more than 12 LED commands (total for all keyboards) per 1/60 second. Even this amount is excessive and should be avoided.

This call may fail due to other traffic on the USB bus. If it returns KBD_ERR_BUSY or if the callback returns KBD_ERR_BUSY, this means the LED command was not sent. In this case, call it again. Because the want is to have the traffic die down before trying again, insert a delay between attempts. It is also acceptable to use the KBDSetLedsRetryEx function instead.

This function will always attempt to send the LED command. Any "lazy (delay)" setting of the LED state must be made at a higher level.

Do Not Call From

Background Do not call this function from the background.

See Also

KBDSetLedsEx
KBDSetLedsRetryEsx

Revision History

2016/06/20 Initial version.


CONFIDENTIAL