iCUE SDK
11 |Overview and Reference
12 |13 |
Protocol version 18
14 | 94 |Overview
96 |The iCUE SDK gives ability for third-party applications to control lightings on Corsair RGB devices. iCUE SDK interacts with hardware through iCUE so it should be running in order for SDK to work properly.
97 |SDK features are supported in iCUE version 4.31 or higher.
98 |To use this SDK you should have basic knowledge in C and library linking.
99 |SDK Package
101 |The following folders are included:
102 |-
103 |
- include contains C/C++ header files with function prototypes and enum declarations; 104 |
- redist contains both 32 and 64 bit .dll files; 105 |
- lib contains companion .lib files to access exported functions (32 and 64 bit); 106 |
- examples contains sample project that shows how to use SDK; 107 |
- doc contains SDK documentation (this document). 108 |
Requirements
112 |This SDK can be used on the same platforms that iCUE does:
113 |-
114 |
- Windows 7 (32-bit and 64-bit); 115 |
- Windows 8 (32-bit and 64-bit); 116 |
- Windows 10 (32-bit and 64-bit). 117 |
- Windows 11 (32-bit and 64-bit). 118 |
Other considerations
123 |LED identification
125 |All supported devices have one or more LED groups. An LED can only belong to one LED group. Each LED within an LED group has its own unique identifier which in this document is defined as the CorsairLedLuid type. The CorsairLedLuid value consists of a group and an LED index/id, structured as follows.
126 || bits 31 .. 16 | 130 |bits 15 .. 0 | 131 |
|---|---|
| LED GROUP | 136 |LED INDEX / ID | 137 |
-
141 |
- LED group - CorsairLedGroup value 142 |
- LED index/id - either a number starting from 1, or a value of specific enumeration (e.g., CorsairLedId_Keyboard). 0 indicates an invalid value. 143 |
Examples:
145 |-
146 |
- 0x00000005 - group is CLG_Keyboard (0), LED is F4 (index is 5, which is CLK_F4 in CorsairLedId_Keyboard) 147 |
- 0x00010001 - group is CLG_KeyboardGKeys (1), LED is G1 key (index is 1) 148 |
- 0x00060001 - group is CLG_Headset (6), LED is the first one on the headset (typically, left) 149 |
Single-color devices
153 |If a connected device only has LEDs of one color instead of all three (RGB) then when RGB color is set to such leds SDK chooses a maximum of three (RGB) values and uses it as brightness for LED.
154 |On/off leds
157 |If a connected device has some LEDs that support only on/off control (as opposed to 8bit) then if supplied brightness value is >= 128 such LED will be switched on, otherwise it will be switched off.
158 |LEDs that are not controlled by SDK
161 |Side LEDs on CORSAIR STRAFE keyboards cannot be controlled by SDK. These LEDs remain controlled by iCUE regardless connected SDK clients.
162 |Some devices have a certain number of service LED indicators (for example, WinLock or Profile LEDs on keyboards) and depending on device model iCUE may, optionally or unconditionally, prohibit controlling these LEDs by SDK. If, however, despite the prohibition on controlling the service LEDs, SDK tries to set a color for them, the new color settings will be ignored for these service LEDs without an error.
163 |Transition between session states
166 |Session states are represented by CorsairSessionState enumeration. SDK client starts with CSS_Closed state. When CorsairConnect function is called, SDK sends notification that it switches to CSS_Connecting state. From CSS_Connecting it may end up with CSS_Connected (if everything is ok), CSS_Timeout (when iCUE was not found) or CSS_ConnectionRefused (if third-party control is disabled in iCUE settings). SDK performs automatic reconnects to go from failing state back to CSS_Connecting.
167 |
168 | After transitioning to CSS_Connected state SDK will notify client application about all connected devices by sending corresponding event for each device. After transitioning to CSS_Closed or CSS_ConnectionLost state SDK will notify client application that all devices have been disconnected by sending corresponding event for each device, also for all G/M/S keys which are in a pressed state at the time one of these states occurred SDK should notify client application that these keys have been released.
169 |Win+L
172 |iCUE will preserve communication channels with SDK clients when user locks screen, so when user session is restored and set of connected devices is unchanged the client can continue using SDK as if the session was never locked.
173 |When user locks screen SDK will perform transition to CSS_ConnectionLost state.
174 |When user unlocks screen SDK will perform transition to CSS_Connected state.
175 |RDP limitations
178 |Both iCUE and SDK are designed to work on a local computer and will not work if accessed remotely through Microsoft RDP.
179 |Access rights
182 |In order to be able to communicate with each other, iCUE and SDK client must run with identical access rights: either with regular access or "As Administrator"
183 |Reference
187 |CorsairSetLedColors
189 |CorsairError CorsairSetLedColors( 190 | const CorsairDeviceId deviceId, 191 | int size, 192 | const CorsairLedColor* ledColors);193 |
Description: sets specified LEDs to some colors. The color is retained until changed by successive calls. This function does not take logical layout into account. This function executes synchronously, if you are concerned about delays consider using CorsairSetLedColorsBuffer together with CorsairSetLedColorsFlushBufferAsync.
194 |Input arguments:
195 |-
196 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 197 |
- int size - number of leds in ledColors array 198 |
- const CorsairLedColor* ledColors - array containing colors for each LED 199 |
Returns: error code. CE_Success if successful. If there is no such ledId present in currently connected hardware (missing key in physical keyboard layout) then functions completes successfully and returns CE_Success.
201 |Possible errors:
202 |-
203 |
- CE_NotConnected, CE_DeviceNotFound 204 |
- CE_InvalidArguments - if deviceId is NULL 205 |
CorsairSetLedColorsBuffer
210 |CorsairError CorsairSetLedColorsBuffer( 211 | const CorsairDeviceId deviceId, 212 | int size, 213 | const CorsairLedColor* ledColors);214 |
Description: sets specified LEDs to some colors. This function sets LEDs colors in the buffer which is written to the devices via CorsairSetLedColorsFlushBufferAsync. Typical usecase is next: CorsairSetLedColorsFlushBufferAsync is called to write LEDs colors to the device and follows after one or more calls of CorsairSetLedColorsBuffer to set the LEDs buffer. This function does not take logical layout into account.
215 |Input arguments:
216 |-
217 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 218 |
- int size - number of leds in ledColors array 219 |
- const CorsairLedColor* ledColors - array containing colors for each LED 220 |
Returns: error code. CE_Success if successful. If there is no such ledId present in currently connected hardware (missing key in physical keyboard layout) then function completes successfully and returns CE_Success.
222 |Possible errors:
223 |-
224 |
- CE_NotConnected, CE_DeviceNotFound 225 |
- CE_InvalidArguments - if deviceId is NULL 226 |
CorsairSetLedColorsFlushBufferAsync
231 |typedef void(*CorsairAsyncCallback)( 232 | void *context, 233 | CorsairError error); 234 | 235 | CorsairError CorsairSetLedColorsFlushBufferAsync( 236 | CorsairAsyncCallback callback, 237 | void *context);238 |
Description: writes to the devices LEDs colors buffer which is previously filled by the CorsairSetLedColorsBuffer function. This function executes asynchronously and returns control to the caller immediately.
239 |Input arguments:
240 |-
241 |
- CorsairAsyncCallback callback - callback that is called by SDK when colors are set. Can be NULL if client is not interested in result. Callback parameters:
242 |
-
243 |
- context - contains value that was supplied by user in CorsairSetLedColorsFlushBufferAsync call. 244 |
- error - error code. CE_Success if the call was successful. Possible errors: CE_NotConnected, CE_NoControl 245 |
247 | - void* context - arbitrary context that will be returned in callback call. Can be NULL 248 |
Returns: error code. CE_Success if successful. If there is no such ledId present in currently connected hardware (missing key in physical keyboard layout, or trying to control mouse while it's disconnected) then function completes successfully and returns CE_Success.
250 |Possible errors:
251 |-
252 |
- CE_NotConnected 253 |
CorsairGetDevices
257 |CorsairError CorsairGetDevices( 258 | const CorsairDeviceFilter *filter, 259 | int sizeMax, 260 | CorsairDeviceInfo *devices, 261 | int *size);262 |
Description: populates the buffer with filtered collection of devices
263 |Input arguments:
264 |-
265 |
- const CorsairDeviceFilter *filter - pointer to filter, that describes which of devices SDK should put to the devices array 266 |
- int sizeMax - size of devices array (should typically be equal to CORSAIR_DEVICE_COUNT_MAX) 267 |
- CorsairDeviceInfo *devices - preallocated buffer that SDK should populate after successful call with information about connected devices that satisfy search criteria specified by filter parameter. 268 |
- int *size - pointer to memory where SDK should store the actual number of items written to devices array. The value should always be less than or equal to sizeMax 269 |
Returns: error code. CE_Success if successful. Also devices array will contain information about devices and size - number of devices in array on return.
271 |Possible errors:
272 |-
273 |
- CE_NotConnected 274 |
- CE_InvalidArguments - if filter is invalid or NULL, if devices array is NULL or too small 275 |
CorsairGetDeviceInfo
279 |CorsairError CorsairGetDeviceInfo( 280 | const CorsairDeviceId deviceId, 281 | CorsairDeviceInfo *deviceInfo);282 |
Description: gets information about device specified by deviceId
283 |Input arguments:
284 |-
285 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 286 |
- CorsairDeviceInfo *deviceInfo - preallocated buffer that SDK should populate after successful call with information about connected device 287 |
Returns: error code. CE_Success if successful. Also deviceInfo will contain valid values read from the device on return.
289 |Possible errors:
290 |-
291 |
- CE_NotConnected, CE_DeviceNotFound 292 |
- CE_InvalidArguments - if deviceInfo is NULL 293 |
CorsairGetDevicePropertyInfo
297 |CorsairError CorsairGetDevicePropertyInfo( 298 | const CorsairDeviceId deviceId, 299 | CorsairDevicePropertyId propertyId, 300 | unsigned int index, 301 | CorsairDataType *dataType, 302 | unsigned int *flags);303 |
Description: gets information about device property for the device specified by deviceId
304 |Input arguments:
305 |-
306 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 307 |
- CorsairDevicePropertyId propertyId - device property identifier 308 |
- unsigned int index - zero based property index; used when property has CPF_Indexed flag set, otherwise should be 0 309 |
- CorsairDataType *dataType - a pointer to the variable to store the returned value of the CorsairDataType enumeration that specifies the type of property data 310 |
- unsigned int *flags - a pointer to the variable to store the returned flag values that describe operations that can be applied to the property. The value is formed as a bitwise "or" of CorsairPropertyFlag enum values 311 |
Returns: error code. CE_Success if successful. Also dataType and flags will contain valid values read from device on return.
313 |Possible errors:
314 |-
315 |
- CE_NotConnected, CE_DeviceNotFound 316 |
- CE_InvalidArguments - if deviceId is NULL, if dataType is NULL or flags is NULL 317 |
- CE_InvalidOperation - if property does not exist for specified device 318 |
CorsairReadDeviceProperty
322 |CorsairError CorsairReadDeviceProperty( 323 | const CorsairDeviceId deviceId, 324 | CorsairDevicePropertyId propertyId, 325 | unsigned int index, 326 | CorsairProperty *property);327 |
Description: gets the data of device property by device identifier, property identifier and property index
328 |Input arguments:
329 |-
330 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 331 |
- CorsairDevicePropertyId propertyId - device property identifier 332 |
- unsigned int index - zero based property index; used when property has CPF_Indexed flag set, otherwise should be 0 333 |
- CorsairProperty *property - a variable to store a pointer to the property data. When SDK client is finished using CorsairProperty instance it should call CorsairFreeProperty function to free memory occupied by struct and its members 334 |
Returns: error code. CE_Success if successful. Also property will contain a pointer to valid property data read from device on return.
336 |Possible errors:
337 |-
338 |
- CE_NotConnected, CE_DeviceNotFound 339 |
- CE_InvalidArguments - if deviceId is NULL or property is NULL 340 |
- CE_InvalidOperation - if property does not exist for specified device 341 |
CorsairWriteDeviceProperty
345 |CorsairError CorsairWriteDeviceProperty( 346 | const CorsairDeviceId deviceId, 347 | CorsairDevicePropertyId propertyId, 348 | unsigned int index, 349 | const CorsairProperty *property);350 |
Description: sets the data of device property by device identifier, property identifier and property index. Can be called only with writable properties
351 |Input arguments:
352 |-
353 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 354 |
- CorsairDevicePropertyId propertyId - device property identifier 355 |
- unsigned int index - zero based property index; used when property has CPF_Indexed flag set, otherwise should be 0 356 |
- const CorsairProperty *property - a pointer to the property data 357 |
Returns: error code. CE_Success if successful.
359 |Possible errors:
360 |-
361 |
- CE_NotConnected, CE_DeviceNotFound 362 |
- CE_InvalidArguments - if deviceId is NULL or property is NULL 363 |
- CE_InvalidOperation - if property does not exist for specified device 364 |
CorsairFreeProperty
368 |CorsairError CorsairFreeProperty(CorsairProperty *property);369 |
Description: frees memory occupied by CorsairProperty instance
370 |Input arguments:
371 |-
372 |
- CorsairProperty *property - a pointer to instance of CorsairProperty for which memory was allocated as a result of a call to CorsairReadDeviceProperty 373 |
Returns: error code. CE_Success if successful.
375 |Possible errors: - CE_InvalidArguments - if property is NULL - CE_InvalidOperation - if SDK failed to free memory for some reason
376 |CorsairGetLedPositions
379 |CorsairError CorsairGetLedPositions( 380 | const CorsairDeviceId deviceId, 381 | int sizeMax, 382 | CorsairLedPosition *ledPositions, 383 | int *size);384 |
Description: provides a list of supported device LEDs by its id with their positions. Position could be either physical (only device-dependent) or logical (depend on device as well as iCUE settings).
385 |Input arguments:
386 |-
387 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 388 |
- int sizeMax - size of ledPositions array (should typically be equal to CORSAIR_DEVICE_LEDCOUNT_MAX) 389 |
- CorsairLedPosition *ledPositions - preallocated buffer that SDK should populate after successful call with the list of LEDs positions 390 |
- int *size - pointer to memory where SDK should store the actual number of items written to ledPositions array. The value should always be less than or equal to sizeMax 391 |
Returns: error code. CE_Success if successful. Also ledPositions array will contain information about LEDs positions and size - number of items in this array on return.
393 |Possible errors:
394 |-
395 |
- CE_NotConnected, CE_DeviceNotFound 396 |
- CE_InvalidArguments - if deviceId is NULL, if ledPositions array is NULL or too small 397 |
CorsairGetLedLuidForKeyName
401 |CorsairError CorsairGetLedLuidForKeyName( 402 | const CorsairDeviceId deviceId, 403 | char keyName, 404 | CorsairLedLuid *luid);405 |
Description: retrieves LED luid for key name taking logical layout into account. So on AZERTY keyboards if user calls CorsairGetLedLuidForKeyName(deviceId, 'A', &luid) he gets luid with CLK_Q code. This luid can be used in CorsairSetLedColors or CorsairSetLedColorsBuffer function
406 |Input arguments:
407 |-
408 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 409 |
- char keyName - key name. ['A'..'Z'] (26 values) are valid values 410 |
- CorsairLedLuid *luid - pointer to memory where SDK should store proper CorsairLedLuid or CLI_Invalid if error occurred 411 |
Returns: error code. CE_Success if successful. Also ledId will contain proper CorsairLedId on return
413 |Possible errors:
414 |-
415 |
- CE_NotConnected, CE_DeviceNotFound 416 |
- CE_InvalidArguments - if deviceId is NULL, if keyName is invalid 417 |
CorsairRequestControl
421 |CorsairError CorsairRequestControl( 422 | const CorsairDeviceId deviceId, 423 | CorsairAccessLevel accessLevel);424 |
Description: requests control using specified access level. By default client has shared control over lighting and events so there is no need to call CorsairRequestControl() unless client requires exclusive control
425 |Input arguments:
426 |-
427 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier. Can be NULL to request control for all devices 428 |
- CorsairAccessLevel accessLevel - requested access level 429 |
Returns: error code. CE_Success if SDK received requested control
431 |Possible errors:
432 |-
433 |
- CE_NotConnected, CE_DeviceNotFound, CE_NoControl 434 |
- CE_InvalidArguments - if provided accessLevel is not supported by this version of SDK 435 |
- CE_NotAllowed - if exclusive control is disabled in iCUE settings 436 |
CorsairReleaseControl
440 |CorsairError CorsairReleaseControl(const CorsairDeviceId deviceId);441 |
Description: releases previously requested control for specified device. This action resets access level to default (shared)
442 |Input arguments:
443 |-
444 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier. Can be NULL to release control for all devices 445 |
Returns: error code. CE_Success if SDK released control
447 |Possible errors:
448 |-
449 |
- CE_NotConnected, CE_DeviceNotFound 450 |
- CE_InvalidArguments - if deviceId is NULL 451 |
Behavior: when this function is called iCUE should clear all colors set by previous calls to CorsairSetLedsColors*` functions if client had exclusive lighting access level and devices should show lightings that come from iCUE. Client may request exclusive control again after calling CorsairReleaseControl
453 |CorsairGetLedColors
456 |CorsairError CorsairGetLedColors( 457 | const CorsairDeviceId deviceId, 458 | int size, 459 | CorsairLedColor* ledColors);460 |
Description: get current color for the list of requested LEDs of supported device. The color should represent the actual state of the hardware LED, which could be a combination of SDK and/or iCUE input.
461 |Input arguments:
462 |-
463 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 464 |
- int size - number of leds in ledColors array 465 |
- CorsairLedColor* ledColors - array containing colors for each LED. Caller should only fill ledId field, and then SDK will fill R, G, B and A values on return. 466 |
Returns: error code. CE_Success if successful. If there is no such ledId present in currently connected hardware (missing key in physical keyboard layout, or trying to control mouse while it's disconnected) then function completes successfully and returns CE_Success. Also ledColors array will contain R, G, B and A values of colors on return
468 |Possible errors:
469 |-
470 |
- CE_NotConnected, CE_DeviceNotFound 471 |
- CE_InvalidArguments - if deviceId is NULL; if array contains duplicates of some led ids 472 |
CorsairSetLayerPriority
476 |CorsairError CorsairSetLayerPriority(unsigned int priority);477 |
Description: set layer priority for this shared client. By default iCUE has priority of 127 and all shared clients have priority of 128 if they don't call this function. Layers with higher priority value are shown on top of layers with lower priority.
478 |Input arguments:
479 |-
480 |
- unsigned int priority - priority of a layer [0..`CORSAIR_LAYER_PRIORITY_MAX`] 481 |
Returns: error code. CE_Success if successful. If this function is called in exclusive mode then it will return CE_Success
483 |Possible errors:
484 |-
485 |
- CE_NotConnected 486 |
- CE_InvalidArguments - if priority value is beyond [0..255] interval 487 |
CorsairSubscribeForEvents
491 |typedef void(*CorsairEventHandler)( 492 | void *context, 493 | const CorsairEvent *event); 494 | 495 | CorsairError CorsairSubscribeForEvents( 496 | CorsairEventHandler onEvent, 497 | void *context);498 |
Description: registers a callback that will be called by SDK when some event happened. If client is already subscribed but calls this function again SDK should use only last callback registered for sending notifications
499 |Input arguments:
500 |-
501 |
- CorsairEventHandler onEvent - callback that is called by SDK when some event happened. Callback parameters:
502 |
-
503 |
- context - contains value that was supplied by user in CorsairSubscribeForEvents call. 504 |
- event - information about event, user can distinguish between events by reading event->id field. 505 |
507 | - void* context - arbitrary context that will be returned in callback call. Can be NULL 508 |
Returns: error code. CE_Success if successful.
510 |Possible errors:
511 |-
512 |
- CE_NotConnected 513 |
- CE_InvalidArguments - if onEvent is NULL 514 |
CorsairUnsubscribeFromEvents
518 |CorsairError CorsairUnsubscribeFromEvents();519 |
Description: unregisters callback previously registered by CorsairSubscribeForEvents call
520 |Input arguments: no
521 |Returns: error code. CE_Success if successful.
522 |Possible errors:
523 |-
524 |
- CE_NotConnected 525 |
CorsairConfigureKeyEvent
529 |CorsairError CorsairConfigureKeyEvent( 530 | const CorsairDeviceId deviceId, 531 | const CorsairKeyEventConfiguration *config);532 |
Description: asks iCUE to send a key event from the device specified by deviceId to an exclusive SDK client only (if config->isIntercepted == true) or to all SDK clients including active exclusive client (if config->isIntercepted == false). Effective only for SDK clients with ExclusiveKeyEventsListening or ExclusiveLightingControlAndKeyEventsListening access level (see CorsairRequestControl). This function gives possibility for a client with ExclusiveKeyEventsListening or ExclusiveLightingControlAndKeyEventsListening access level to control selected set of macro keys only and let iCUE to pass some key events to other shared clients
533 |Input arguments:
534 |-
535 |
- const CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 536 |
- CorsairKeyEventConfiguration* config - key event configuration. If config->isIntercepted equals true then iCUE should pass the event to an active exclusive SDK client only. If false then iCUE should send it to all the clients. 537 |
Returns: error code. CE_Success if configuration was successfully applied or it was not changed (but no error occurred).
539 |Possible errors:
540 |-
541 |
- CE_NotConnected 542 |
- CE_NotAllowed - if exclusive control is disabled in iCUE settings 543 |
- CE_NoControl - if some other client has or took over exclusive control 544 |
- CE_InvalidOperation - if client has insufficient access level (must have ExclusiveKeyEventsListening or ExclusiveLightingControlAndKeyEventsListening access level) 545 |
- CE_InvalidArguments - if deviceId or config is NULL 546 |
CorsairConnect
550 |typedef void(*CorsairSessionStateChangedHandler)( 551 | void *context, 552 | const CorsairSessionStateChanged *eventData); 553 | 554 | CorsairError CorsairConnect( 555 | CorsairSessionStateChangedHandler onStateChanged, 556 | void *context);557 |
Description: sets handler for session state changes, checks versions of SDK client, server and host (iCUE) to understand which of SDK functions can be used with this version of iCUE
558 |Input arguments:
559 |CorsairSessionStateChangedHandler onStateChanged - callback that is called by SDK when session state changed. Callback parameters:
560 |561 |566 |562 |
565 |- context - contains value that was supplied by user in CorsairConnect call.
563 |- eventData - information about new session state and client/server versions.
564 |
-
567 |
- void* context - arbitrary context that will be returned in callback call. Can be NULL 568 |
Returns: error code. CE_Success if successful.
570 |Possible errors:
571 |-
572 |
- CE_InvalidArguments - if onStateChanged is NULL 573 |
- CE_InvalidOperation - if SDK client is already connected or is connecting 574 |
CorsairGetSessionDetails
578 |CorsairError CorsairGetSessionDetails( 579 | CorsairSessionDetails* details);580 |
Description: checks versions of SDK client, server and host (iCUE) to understand which of SDK functions can be used with this version of iCUE. If there is no active session or client is not connected to the server, then only client version will be filled
581 |Input arguments:
582 |-
583 |
- CorsairSessionDetails* details - pointer to preallocated memory where to store information about SDK and iCUE versions. 584 |
Returns: error code. CE_Success if successful.
586 |Possible errors:
587 |CE_InvalidArguments - if details is NULL
588 |CorsairDisconnect
591 |CorsairError CorsairDisconnect();592 |
Description: removes handler for session state changes previously set by CorsairConnect
593 |Input arguments: no
594 |Returns: error code. CE_Success if successful.
595 |Possible errors:
596 |-
597 |
- CE_NotConnected 598 |
Behavior: before function returns session state event will be triggered with state changed to CSS_Closed
600 |CorsairLedGroup
603 |enum CorsairLedGroup604 |
Description: contains a list of led groups. Led group is used as a part of led identifier
605 |Items:
606 |-
607 |
- CLG_Keyboard - for keyboard leds 608 |
- CLG_KeyboardGKeys - for keyboard leds on G keys 609 |
- CLG_KeyboardEdge - for keyboard lighting pipe leds 610 |
- CLG_KeyboardOem - for vendor specific keyboard leds (ProfileSwitch, DialRing, etc.) 611 |
- CLG_Mouse - for mouse leds 612 |
- CLG_Mousemat - for mousemat leds 613 |
- CLG_Headset - for headset leds 614 |
- CLG_HeadsetStand - for headset stand leds 615 |
- CLG_MemoryModule - for memory module leds 616 |
- CLG_Motherboard - for motherboard leds 617 |
- CLG_GraphicsCard - for graphics card leds 618 |
- CLG_DIY_Channel1 - for leds on the first channel of DIY devices and coolers 619 |
- CLG_DIY_Channel2 - for leds on the second channel of DIY devices and coolers 620 |
- CLG_DIY_Channel3 - for leds on the third channel of DIY devices and coolers 621 |
- CLG_Touchbar - for touchbar leds 622 |
- CLG_GameController - for game controller leds 623 |
CorsairLedId_Keyboard
627 |enum CorsairLedId_Keyboard628 |
Description: contains a list of keyboard leds that belong to CLG_Keyboard group
629 |Item samples:
630 |-
631 |
- CLI_Invalid - dummy value 632 |
- CLK_F1, CLK_Esc, CLK_Q, CLK_1, CLK_ArrowUp, ... - for keyboard leds 633 |
CorsairMacroKeyId
637 |enum CorsairMacroKeyId638 |
Description: contains a shared list of G, M and S keys (not all available keys!)
639 |Item samples:
640 |-
641 |
- CMKI_Invalid - dummy value 642 |
- CMKI_1, ... CMKI_20 - for keyboard G keys, mouse M keys or touchbar S keys 643 |
CorsairDeviceType
647 |enum CorsairDeviceType648 |
Description: contains list of available device types
649 |Items:
650 |-
651 |
- CDT_Unknown = 0x0000 - for unknown/invalid devices 652 |
- CDT_Keyboard = 0x0001 - for keyboards 653 |
- CDT_Mouse = 0x0002 - for mice 654 |
- CDT_Mousemat = 0x0004 - for mousemats 655 |
- CDT_Headset = 0x0008 - for headsets 656 |
- CDT_HeadsetStand = 0x0010 - for headset stands 657 |
- CDT_FanLedController = 0x0020 - for DIY-devices like Commander PRO 658 |
- CDT_LedController = 0x0040 - for DIY-devices like Lighting Node PRO 659 |
- CDT_MemoryModule = 0x0080 - for memory modules 660 |
- CDT_Cooler = 0x0100 - for coolers 661 |
- CDT_Motherboard = 0x0200 - for motherboards 662 |
- CDT_GraphicsCard = 0x0400 - for graphics cards 663 |
- CDT_Touchbar = 0x0800 - for touchbars 664 |
- CDT_GameController = 0x1000 - for game controllers 665 |
- CDT_All = 0xFFFFFFFF - for all devices 666 |
CorsairChannelDeviceType
670 |enum CorsairChannelDeviceType671 |
Description: contains list of the LED-devices which can be connected to the DIY-device, memory module or cooler.
672 |Items:
673 |-
674 |
- CCDT_Invalid - dummy value 675 |
- CCDT_HD_Fan, CCDT_SP_Fan, CCDT_LL_Fan, CCDT_ML_Fan, CCDT_QL_Fan, CCDT_8LedSeriesFan, CCDT_Strip, CCDT_DAP, CCDT_Pump, CCDT_DRAM, CCDT_WaterBlock, CCDT_QX_Fan - valid values 676 |
CorsairPhysicalLayout
680 |enum CorsairPhysicalLayout681 |
Description: contains list of available physical layouts for keyboards
682 |Items:
683 |-
684 |
- CPL_Invalid - dummy value 685 |
- CPL_US, CPL_UK, CPL_JP, CPL_KR, CPL_BR - valid values 686 |
CorsairLogicalLayout
690 |enum CorsairLogicalLayout691 |
Description: contains list of available logical layouts for keyboards
692 |Items:
693 |-
694 |
- CLL_Invalid - dummy value 695 |
- CLL_US_Int, CLL_NA, CLL_EU, CLL_UK, CLL_BE, CLL_BR, CLL_CH, CLL_CN, CLL_DE, CLL_ES, CLL_FR, CLL_IT, CLL_ND, CLL_RU, CLL_JP, CLL_KR, CLL_TW, CLL_MEX - valid values 696 |
CorsairSessionState
700 |enum CorsairSessionState701 |
Description: contains a list of all possible session states
702 |Items:
703 |-
704 |
- CSS_Invalid = 0 - dummy value 705 |
- CSS_Closed = 1 - client not initialized or client closed connection (initial state) 706 |
- CSS_Connecting = 2 - client initiated connection but not connected yet 707 |
- CSS_Timeout = 3 - server did not respond, sdk will try again 708 |
- CSS_ConnectionRefused = 4 - server did not allow connection 709 |
- CSS_ConnectionLost = 5 - server closed connection 710 |
- CSS_Connected = 6 - successfully connected 711 |
CorsairError
715 |enum CorsairError716 |
Description: contains shared list of all errors which could happen during calling of Corsair* functions
717 |Items:
718 |-
719 |
- CE_Success - if previously called function completed successfully 720 |
- CE_NotConnected - if iCUE is not running or was shut down or third-party control is disabled in iCUE settings (runtime error), or if developer did not call CorsairConnect after calling CorsairDisconnect or on app start (developer error) 721 |
- CE_NoControl - if some other client has or took over exclusive control (runtime error) 722 |
- CE_IncompatibleProtocol - if developer is calling the function that is not supported by the server (either because protocol has broken by server or client or because the function is new and server is too old. Check CorsairSessionDetails for details) (developer error) 723 |
- CE_InvalidArguments - if developer supplied invalid arguments to the function (for specifics look at function descriptions) (developer error) 724 |
- CE_InvalidOperation - if developer is calling the function that is not allowed due to current state (reading improper properties from device, or setting callback when it has already been set) (developer error) 725 |
- CE_DeviceNotFound - if invalid device id has been supplied as an argument to the function (when device id refers to disconnected device) (runtime error) 726 |
- CE_NotAllowed - if specific functionality (key interception) is disabled in iCUE settings (runtime error) 727 |
CorsairAccessLevel
731 |enum CorsairAccessLevel732 |
Description: contains list of available SDK access levels
733 |Items:
734 |-
735 |
- CAL_Shared = 0 - shared mode (default) 736 |
- CAL_ExclusiveLightingControl = 1 - exclusive lightings, but shared events 737 |
- CAL_ExclusiveKeyEventsListening = 2 - exclusive key events, but shared lightings 738 |
- CAL_ExclusiveLightingControlAndKeyEventsListening = 3 - exclusive mode 739 |
CorsairEventId
743 |enum CorsairEventId744 |
Description: contains list of event identifiers
745 |Items:
746 |-
747 |
- CEI_Invalid - dummy value, 748 |
- CEI_DeviceConnectionStatusChangedEvent, CEI_KeyEvent - valid values 749 |
CorsairDevicePropertyId
753 |enum CorsairDevicePropertyId754 |
Description: contains list of properties identifiers which can be read from device.
755 |Items:
756 |-
757 |
- CDPI_Invalid = 0 - dummy value 758 |
- CDPI_PropertyArray = 1 - array of CorsairDevicePropertyId members supported by device 759 |
- CDPI_MicEnabled = 2 - indicates Mic state (On or Off); used for headset, headset stand 760 |
- CDPI_SurroundSoundEnabled = 3 - indicates Surround Sound state (On or Off); used for headset, headset stand 761 |
- CDPI_SidetoneEnabled = 4 - indicates Sidetone state (On or Off); used for headset (where applicable) 762 |
- CDPI_EqualizerPreset = 5 - the number of active equalizer preset (integer, 1 - 5); used for headset, headset stand 763 |
- CDPI_PhysicalLayout = 6 - keyboard physical layout (see CorsairPhysicalLayout for valid values); used for keyboard 764 |
- CDPI_LogicalLayout = 7 - keyboard logical layout (see CorsairLogicalLayout for valid values); used for keyboard 765 |
- CDPI_MacroKeyArray = 8 - array of programmable G, M or S keys on device 766 |
- CDPI_BatteryLevel = 9 - battery level (0 - 100); used for wireless devices 767 |
- CDPI_ChannelLedCount = 10 - total number of LEDs connected to the channel 768 |
- CDPI_ChannelDeviceCount = 11 - number of LED-devices (fans, strips, etc.) connected to the channel which is controlled by the DIY device 769 |
- CDPI_ChannelDeviceLedCountArray = 12 - array of integers, each element describes the number of LEDs controlled by the channel device 770 |
- CDPI_ChannelDeviceTypeArray = 13 - array of CorsairChannelDeviceType members, each element describes the type of the channel device 771 |
CorsairDataType
775 |enum CorsairDataType776 |
Description: contains list of available property types
777 |Items:
778 |-
779 |
- CT_Boolean = 0 - for property of type Boolean 780 |
- CT_Int32 = 1 - for property of type Int32 or Enumeration 781 |
- CT_Float64 = 2 - for property of type Float64 782 |
- CT_String = 3 - for property of type String 783 |
- CT_Boolean_Array = 16 - for array of Boolean 784 |
- CT_Int32_Array = 17 - for array of Int32 785 |
- CT_Float64_Array = 18 - for array of Float64 786 |
- CT_String_Array = 19 - for array of String 787 |
CorsairPropertyFlag
791 |enum CorsairPropertyFlag792 |
Description: contains list of operations that can be applied to the property
793 |Items:
794 |-
795 |
- CPF_None = 0x00 796 |
- CPF_CanRead = 0x01 - describes readable property 797 |
- CPF_CanWrite = 0x02 - describes writable property 798 |
- CPF_Indexed = 0x04 - if flag is set, then index should be used to read/write multiple properties that share the same property identifier 799 |
CorsairLedColor
803 |struct CorsairLedColor804 |
Description: contains information about LED and its color
805 |Fields:
806 |-
807 |
- CorsairLedLuid id - unique identifier of led 808 |
- unsigned char r - red brightness [0..255] 809 |
- unsigned char g - green brightness [0..255] 810 |
- unsigned char b - blue brightness [0..255] 811 |
- unsigned char a - alpha channel [0..255]. The opacity of the color from 0 for completely translucent to 255 for opaque 812 |
CorsairLedPosition
816 |struct CorsairLedPosition817 |
Description: contains led id and position of led.
818 |Fields:
819 |-
820 |
- CorsairLedLuid id - unique identifier of led 821 |
- double cx, double cy - for keyboards, mice, mousemats, headset stands and memory modules values are in mm, for DIY-devices, headsets and coolers values are in logical units 822 |
CorsairDeviceInfo
826 |struct CorsairDeviceInfo827 |
Description: contains information about device
828 |Fields:
829 |-
830 |
- CorsairDeviceType type - enum describing device type 831 |
- CorsairDeviceId id - null terminated Unicode string that contains unique device identifier 832 |
- char serial[CORSAIR_STRING_SIZE_M] - null terminated Unicode string that contains device serial number. Can be empty, if serial number is not available for the device 833 |
- char model[CORSAIR_STRING_SIZE_M] - null terminated Unicode string that contains device model (like "K95RGB") 834 |
- int ledCount - number of controllable LEDs on the device 835 |
- int channelCount - number of channels controlled by the device 836 |
CorsairDeviceFilter
840 |struct CorsairDeviceFilter841 |
Description: contains device search filter.
842 |Fields:
843 |-
844 |
- int deviceTypeMask - mask that describes device types, formed as logical "or" of CorsairDeviceType enum values 845 |
CorsairVersion
849 |struct CorsairVersion850 |
Description: contains information about version that consists of three components
851 |Fields:
852 |-
853 |
- int major 854 |
- int minor 855 |
- int patch 856 |
CorsairSessionDetails
860 |struct CorsairSessionDetails861 |
Description: contains information about SDK and iCUE versions
862 |Fields:
863 |-
864 |
- CorsairVersion clientVersion - version of SDK client (like {4,0,1}). Always contains valid value even if there was no iCUE found. Must comply with the semantic versioning rules. 865 |
- CorsairVersion serverVersion - version of SDK server (like {4,0,1}) or empty struct ({0,0,0}) if the iCUE was not found. Must comply with the semantic versioning rules. 866 |
- CorsairVersion serverHostVersion - version of iCUE (like {4,30,58}) or empty struct ({0,0,0}) if the iCUE was not found. 867 |
CorsairSessionStateChanged
871 |struct CorsairSessionStateChanged872 |
Description: contains information about session state and client/server versions
873 |Fields:
874 |-
875 |
- CorsairSessionState state - new session state which SDK client has been transitioned to 876 |
- CorsairSessionDetails details - information about client/server versions 877 |
CorsairEvent
881 |struct CorsairEvent882 |
Description: contains information about event id and event data
883 |Fields:
884 |-
885 |
- CorsairEventId id - event identifier 886 |
-
887 |
-
888 |
- Anonymous union with fields: 889 |
-
890 |
-
891 |
- const CorsairDeviceConnectionStatusChangedEvent *deviceConnectionStatusChangedEvent - when id == CEI_DeviceConnectionStatusChangedEvent contains valid pointer to structure with information about connected or disconnected device 892 |
- const CorsairKeyEvent *keyEvent - when id == CEI_KeyEvent contains valid pointer to structure with information about pressed or released G, M or S button and device where this event happened 893 |
895 |
897 |
CorsairDeviceConnectionStatusChangedEvent
901 |struct CorsairDeviceConnectionStatusChangedEvent902 |
Description: contains information about device that was connected or disconnected
903 |Fields:
904 |-
905 |
- CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 906 |
- bool isConnected - true if connected, false if disconnected 907 |
CorsairKeyEvent
911 |struct CorsairKeyEvent912 |
Description: contains information about device where G, M or S key was pressed/released and the key itself
913 |Fields:
914 |-
915 |
- CorsairDeviceId deviceId - null terminated Unicode string that contains unique device identifier 916 |
- CorsairMacroKeyId keyId - G, M or S key that was pressed/released 917 |
- bool isPressed - true if pressed, false if released 918 |
CorsairKeyEventConfiguration
922 |struct CorsairKeyEventConfiguration923 |
Description: contains information about key event configuration
924 |Fields:
925 |-
926 |
- CorsairMacroKeyId keyId - G, M or S key 927 |
- bool isIntercepted - flag that defines how key event should behave. If true then iCUE will pass the event to an active exclusive SDK client and stop passing it to the rest SDK clients. If false then iCUE will resume sending it to all SDK clients 928 |
CorsairDataType_BooleanArray
932 |struct CorsairDataType_BooleanArray933 |
Description: represents an array of boolean values
934 |Fields:
935 |-
936 |
- bool* items - an array of boolean values 937 |
- unsigned int count - number of items array elements 938 |
CorsairDataType_Int32Array
942 |struct CorsairDataType_Int32Array943 |
Description: represents an array of integer values
944 |Fields:
945 |-
946 |
- int* items - an array of integer values 947 |
- unsigned int count - number of items array elements 948 |
CorsairDataType_Float64Array
952 |struct CorsairDataType_Float64Array953 |
Description: represents an array of double values
954 |Fields:
955 |-
956 |
- double* items - an array of double values 957 |
- unsigned int count - number of items array elements 958 |
CorsairDataType_StringArray
962 |struct CorsairDataType_StringArray963 |
Description: represents an array of pointers to null terminated strings
964 |Fields:
965 |-
966 |
- char** items - an array of pointers to null terminated strings 967 |
- unsigned int count - number of items array elements 968 |
CorsairDataValue
972 |union CorsairDataValue973 |
Description: a union of all property data types
974 |Fields:
975 |-
976 |
- bool boolean - actual property value if it's type is CPDT_Boolean 977 |
- int int32 - actual property value if it's type is CPDT_Int32 978 |
- double float64 - actual property value if it's type is CPDT_Float64 979 |
- char* string - actual property value if it's type is CPDT_String 980 |
- CorsairDataType_BooleanArray boolean_array - actual property value if it's type is CPDT_Boolean_Array 981 |
- CorsairDataType_Int32Array int32_array - actual property value if it's type is CPDT_Int32_Array 982 |
- CorsairDataType_Float64Array float64_array - actual property value if it's type is CPDT_Float64_Array 983 |
- CorsairDataType_StringArray string_array - actual property value if it's type is CPDT_String_Array 984 |
CorsairProperty
988 |struct CorsairProperty989 |
Description: contains information about device property type and value
990 |Fields:
991 |-
992 |
- CorsairDataType type - type of property 993 |
- CorsairDataValue value - property value 994 |
End User License Agreement
999 |On-Line End User License Agreement
1000 |IMPORTANT: This End-User License Agreement ("EULA") is a legal Agreement between you and Corsair Components Inc., and any of its affiliates and/or subsidiaries ("CORSAIR") with respect to the software, SDKs and source code provided by CORSAIR, any associated media, printed materials, "online" documentation and electronic documentation (collectively referred to as "Software"). By installing, copying, or otherwise using the Software, you agree to be bound by the terms of this EULA. "You" and "Your" may refer to a natural person or to a legal entity including, but not limited to, a corporation, partnership or a limited liability company. If you do not agree to the terms of this EULA, you are not authorized to install or use the Software.
1001 |-
1002 |
- Ownership of Software. 1003 |
CORSAIR owns certain rights in the Software. THE SOFTWARE IS A PROPRIETARY PRODUCT OF CORSAIR OR THIRD PARTIES FROM WHOM CORSAIR HAS OBTAINED LICENSING RIGHTS. THE SOFTWARE IS PROTECTED BY COPYRIGHT LAWS AND OTHER INTELLECTUAL PROPERTY LAWS. TITLE TO THIS SOFTWARE, ANY COPY OF THIS SOFTWARE, AND ANY INTELLECTUAL PROPERTY RIGHTS IN THE SOFTWARE WILL AT ALL TIMES REMAIN WITH CORSAIR AND SUCH THIRD PARTIES. Your rights are defined by this Agreement which You agree creates a legally binding and valid contract. CORSAIR retains the right to utilize its affiliated companies, authorized distributors, authorized resellers and other third parties in pursuing any of its rights and fulfilling any of its obligations under this Agreement.
1005 |-
1006 |
- License Grant. 1007 |
CORSAIR grants to You a nonexclusive, nontransferable (except as may be required by applicable law) royalty-free license to allow You to use the Software.
1009 |-
1010 |
- Your Responsibilities and Prohibited Actions. 1011 |
(a) Transfer of Rights. You may not transfer or assign all or any portion of the Software, or any rights granted in this Agreement, to any other person.
1013 |(b) Reverse Engineering or Modifying the Software. You will not reverse engineer, decompile, translate, disassemble, or otherwise attempt to discover the source code of the Software. The prohibition against modifying or reverse engineering the Software does not apply to the extent that You are allowed to do so by applicable law including, but not limited to, the European Union Directive on the Interoperability of Software or its implementing legislation in the member countries. You may not otherwise modify, alter, adapt, or merge the Software.
1014 |(c) Third Party Supplier. You agree that CORSAIR's third party suppliers may enforce this Agreement as it relates to their Software directly against You.
1015 |(d) Export. CORSAIR shall not be required to undertake any action pursuant to this Agreement that is prevented by any impediments arising out of national or international foreign trade or customs requirements, including embargoes or any other sanctions. This Agreement is subject to all United States government laws and regulations as may be enacted, amended or modified from time to time regarding the export from the United States of CORSAIR software, services, technology, or any derivatives thereof. You will not export or re-export any CORSAIR software, services, technology, or any derivatives thereof, or permit the shipment of same. This section will survive the expiration or termination of this Agreement for any reason.
1016 |-
1017 |
- Term and Termination. 1018 |
CORSAIR reserves the right to terminate this Agreement if You fail to comply with any of the terms described herein. All license rights granted will cease upon any termination of this Agreement.
1020 |-
1021 |
- Disclaimer of Warranty. 1022 |
CORSAIR MAKES NO WARRANTIES OF ANY KIND, AND NO WARRANTY IS GIVEN THAT THE SOFTWARE IS ERROR-FREE OR THAT ITS USE WILL BE UNINTERRUPTED OR THAT IT WILL WORK IN CONNECTION WITH ANY OTHER SOFTWARE. ALL WARRANTIES, CONDITIONS, REPRESENTATIONS, INDEMNITIES AND GUARANTEES, WHETHER EXPRESS OR IMPLIED, ARISING BY LAW, CUSTOM, PRIOR ORAL OR WRITTEN STATEMENTS (INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR PARTICULAR PURPOSE OR OF ERROR-FREE AND UNINTERRUPTED USE OR ANY WARRANTY AGAINST INFRINGEMENT) ARE HEREBY OVERRIDDEN, EXCLUDED AND DISCLAIMED, EXCEPT AS OTHERWISE EXPRESSLY STATED IN THIS LICENSE AGREEMENT.
1024 |-
1025 |
- Limitation of Liability. 1026 |
CORSAIR's entire liability for all claims or damages arising out of or related to this Agreement, regardless of the form of action, whether in contract, equity, negligence, intended conduct, tort or otherwise, will be limited to and will not exceed, in the aggregate for all claims, actions and causes of action of every kind and nature; the amount paid to CORSAIR for the specific item that caused the damage or that is the subject matter of the cause of action. In no event will the measure of damages payable by CORSAIR include, nor will CORSAIR be liable for, any amounts for loss of income, profit or savings or indirect, incidental, consequential, exemplary, punitive or special damages of any party, including third parties, even if CORSAIR has been advised of the possibility of such damages in advance, and all such damages are expressly disclaimed. This section shall not be interpreted to exclude any liability that is prohibited from being excluded by applicable law. Except as otherwise provided by applicable law, no claim, regardless of form, arising out of or in connection with this Agreement may be brought by You unless such claim is brought either (i) within two years after the cause of action has accrued or (ii) within the shortest period of time after the cause of action has accrued that may be legally contracted for in the applicable jurisdiction if a two year limitation would be legally unenforceable.
1028 |-
1029 |
- Software Support Services. 1030 |
CORSAIR offers technical support services. See www.corsair.com. Such technical support shall be provided in CORSAIR's sole discretion without any guarantee or warranty of any kind. It is your responsibility to back up of all your existing data, software and programs before receiving any technical support from CORSAIR. CORSAIR reserves the right to refuse, suspend or terminate any technical support, in its sole discretion.
1032 |-
1033 |
- Choice of Law and Jurisdiction. 1034 |
This Agreement will be governed by and construed in accordance with the substantive laws of the State of California in the United States, without giving effect to any choice-of-law rules that may require the application of the laws of another jurisdiction. This Agreement will not be governed by the United Nations Convention on Contracts for the International Sale of Goods, the application of which is expressly excluded. Any disputes arising under this Agreement shall be settled exclusively in the California state courts or United States federal courts located in California. The parties hereby submit to the personal jurisdiction of such courts for the purpose of resolving any dispute under this Agreement.
1036 |-
1037 |
- Severability/Reformation. 1038 |
If any provision of this Agreement is found to be void or unenforceable, it will not affect the validity of any other provision of this Agreement and those provisions will remain valid and enforceable according to their terms. To the extent that an unenforceable provision may be reformed to be enforceable by a court of law, such provision will be deemed to be so reformed in this Agreement.
1040 |-
1041 |
- Other Rights Reserved. 1042 |
All rights not specifically granted in this Agreement are reserved by CORSAIR.
1044 |-
1045 |
- Entire Agreement. 1046 |
You acknowledge that You have read this Agreement, understand it and agree to be bound by its terms and conditions. You further agree that it is the complete and exclusive statement of the agreement between us which supersedes any proposal or prior agreement, oral or written, and any other communications between us relating to the subject matter of this Agreement.
1048 |