C.2. WinDriver IPC API Reference

This section describes the WinDriver IPC API defined in the WinDriver/include/wds_lib.h header file.

C.2.1. IPC_MSG_RX_HANDLER()

Purpose

WinDriver IPC message handler callback.

Prototype
typedef void (*IPC_MSG_RX_HANDLER)(
    WDS_IPC_MSG_RX *pIpcRxMsg,
    void *pData);
Parameters
NameTypeInput/Output
pIpcRxMsgWDS_IPC_MSG_RX *Input
• dwSenderUIDDWORDInput
• dwMsgIDDWORDInput
• qwMsgDataUINT64Input
pDatavoid *Input
Description
NameDescription
pIpcRxMsgPointer to the received IPC message
• dwSenderUIDWinDriver IPC unique ID of the sending process
• dwMsgID A 32 bit unique number defined by the user application. This number should be known to all user-applications that work under WinDriver IPC and share the same group ID
• qwMsgData Optional - 64 bit additional data from the sending user-application process
pData Application specific data opaque as passed to WDS_IpcRegister() [C.2.2]

C.2.2. WDS_IpcRegister()

Purpose

Registers an application with WinDriver IPC.

[Note]
This API is not part of the standard WinDriver APIs, and is not included in the standard version of WinDriver. It is part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Prototype
DWORD DLLCALLCONV WDS_IpcRegister(
    const CHAR *pcProcessName,
    DWORD dwGroupID,
    DWORD dwSubGroupID,
    DWORD dwAction,
    IPC_MSG_RX_HANDLER pFunc,
    void *pData);
Parameters
NameTypeInput/Output
pcProcessNameconst CHAR*Input
dwGroupIDDWORDInput
dwSubGroupIDDWORDInput
dwActionDWORDInput
pFunc see IPC_MSG_RX_HANDLER() [C.2.1] Input
pDatavoid*Input
Description
NameDescription
pcProcessNameOptional process name string
dwGroupID A unique group ID represent the specific application. Must be a positive ID
dwSubGroupID Sub-group ID that should identify your user application type in case you have several types that may work simultaneously. Must be a positive ID
dwAction

IPC message type to receive, which can consist one of the enumeration values listed below:

WD_IPC_UNICAST_MSG:
WD_IPC_MULTICAST_MSG:
WD_IPC_ALL_MSG:

pFunc A user-mode IPC message handler callback function, which will be called when a message was received by WinDriver from a different process (see dwActions) occurs. (See IPC_MSG_RX_HANDLER() [C.2.1])
pData Data for the user-mode IPC message handler callback routine (pFunc)
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].

Remarks
  • You should choose your user applications a unique group ID parameter. This is done as a precaution to prevent several applications that use WinDriver with its default driver name (windrvrXXXX) to get mixing messages. We strongly recommend that you rename your driver before distributing it to avoid this issue entirely, among other issue (See Section 15.2 on renaming you driver name).
  • The sub-group id parameter should identify your user application type in case you have several types that may work simultaneously.

C.2.3. WDS_IpcUnRegister()

Purpose

This function enables the user application to unregister with WinDriver IPC.

[Note]
This API is not part of the standard WinDriver APIs, and is not included in the standard version of WinDriver. It is part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Prototype
DWORD DLLCALLCONV WDS_IpcUnRegister(void);
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].

C.2.4. WDS_IsIpcRegistered()

Purpose

Enables the application to check if it is already registered with WinDriver IPC.

[Note]
This API is not part of the standard WinDriver APIs, and is not included in the standard version of WinDriver. It is part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Prototype
DWORD DLLCALLCONV WDS_IsIpcRegistered(void);
Return Value

Returns TRUE if successful; otherwise returns FALSE.

C.2.5. WDS_IpcScanProcs()

Purpose

Scans and returns information of all registered processes that share the application process groupID (as was given to WDS_IpcRegister() [C.2.2] or a specific groupID.

[Note]
This API is not part of the standard WinDriver APIs, and is not included in the standard version of WinDriver. It is part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Prototype
DWORD DLLCALLCONV WDS_IpcScanProcs(
    DWORD dwGroupID,
    WDS_IPC_SCAN_RESULT *ipcScanProcs);
Parameters
NameTypeInput/Output
dwGroupIDDWORDInput
ipcScanProcsWDS_IPC_SCAN_RESULT*Output
• dwNumProcsDWORDOutput
• procInfoWD_IPC_PROCESS[]Output
 * cProcessNameCHAR*Output
 * dwSubGroupIDDWORDOutput
 * dwGroupIDDWORDOutput
 * hIpcDWORDOutput
Description
NameDescription
dwGroupID 0 - Scan processes that share the current process group ID. Other - Scan for all processes that registered with the specific group ID.
ipcScanProcs 
• dwNumProcsNumber of matching processes
• procInfoAn array of matching processes[]
 * cProcessNameMatched process name
 * dwSubGroupIDUnique identifier of the process sub-group
 * dwGroupID10. Jungo reserves the right to revise, update, change, modify, add to, supplement, or delete any and all terms of this License Agreement; provided, however, that changes to this License Agreement will not be applied retroactively. Such changes will be effective with or without prior notice to you. You can review the most current version of this License Agreement under the WinDriver download form page. Unique identifier of the processes group for discarding unrelated processes
 * hIpc IPC handle as returned by the low-level WD_IpcRegister() function
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].

C.2.6. WDS_IpcMulticast()

Purpose

Sends a message to all processes that were registered with the same group ID as the sending process.

[Note]
This API is not part of the standard WinDriver APIs, and is not included in the standard version of WinDriver. It is part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Prototype
DWORD DLLCALLCONV WDS_IpcMulticast(
    DWORD dwMsgID,
    UINT64 qwMsgData);
Parameters
NameTypeInput/Output
dwMsgIDDWORDInput
qwMsgDataUINT64Input
Description
NameDescription
dwMsgID A 32 bit unique number defined by the user application. This number should be known to all user-applications that work under WinDriver IPC and share the same group ID
qwMsgData Optional - 64 bit additional data from the sending user-application
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].

C.2.7. WDS_IpcSubGroupMulticast()

Purpose

Sends a message to all processes that registered with the same sub-group ID

[Note]
This API is not part of the standard WinDriver APIs, and is not included in the standard version of WinDriver. It is part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Prototype
DWORD DLLCALLCONV WDS_IpcSubGroupMulticast(
    DWORD dwRecipientSubGroupID,
    DWORD dwMsgID,
    UINT64 qwMsgData);
Parameters
NameTypeInput/Output
dwRecipientSubGroupIDDWORDInput
dwMsgIDDWORDInput
qwMsgDataUINT64Input
Description
NameDescription
dwRecipientSubGroupID Recipient sub-group ID that should identify your user application type in case you have several types that may work simultaneously.
dwMsgID A 32 bit unique number defined by the user application. This number should be known to all user-applications that work under WinDriver IPC and share the same group ID
qwMsgData Optional - 64 bit additional data from the sending user-application
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].

C.2.8. WDS_IpcUidUnicast()

Purpose

Sends a message to a specific process with WinDriver IPC unique ID

[Note]
This API is not part of the standard WinDriver APIs, and is not included in the standard version of WinDriver. It is part of "WinDriver for Server" API and requires "WinDriver for Server" license. Note that "WinDriver for Server" APIs are included in WinDriver evaluation version.
Prototype
DWORD DLLCALLCONV WDS_IpcUidUnicast(
    DWORD dwRecipientUID,
    DWORD dwMsgID,
    UINT64 qwMsgData);
Parameters
NameTypeInput/Output
dwRecipientUIDDWORDInput
dwMsgIDDWORDInput
qwMsgDataUINT64Input
Description
NameDescription
dwRecipientUID WinDriver IPC unique ID that should identify one of your user application. The reciepient UID can be obtained from the result of WDS_IpcScanProcs() [C.2.5] or the sender ID as received in the callback registered in WDS_IpcRegister() [C.2.2]
dwMsgID A 32 bit unique number defined by the user application. This number should be known to all user-applications that work under WinDriver IPC and share the same group ID
qwMsgData Optional - 64 bit additional data from the sending user-application
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [B.11].