niSE_FindRoute
- Updated2023-02-21
- 3 minute(s) read
niSE_FindRoute
Finds an existing or potential route between channel 1 and channel 2.
Function Prototype
| NISEStatus __stdcall niSE_FindRoute( | NISESession sessionHandle, |
| NISEConstString channel1, | |
| NISEConstString channel2, | |
| NISEBuffer* routeSpec, | |
| NISEInt32 * routeSpecSize, | |
| NISEInt32 * routeCapability); |
Parameters
Input
| Name | Type | Description |
|---|---|---|
| sessionHandle | NISESession | The session referencing this NI Switch Executive virtual device session. |
| channel1 | NISEConstString | The channel name of one of the endpoints of the route to find. The channel name must either be a channel alias name or a name in the device/ivichannel syntax. Examples: |
| channel2 | NISEConstString | The channel name of one of the endpoints of the route to find. The channel name must either be a channel alias name or a name in the device/ivichannel syntax. Examples: |
Input/Output
| Name | Type | Description |
|---|---|---|
| routeSpecSize | NISEInt32 | The routeSpecSize is an NISEInt32 that is passed by reference into the
function.
As an input, it is the size of the route string buffer being passed. If the route string is larger than the string buffer being passed, only the portion of the route string that can fit in the string buffer is copied into it. On return from the function, routeSpecSize holds the size required to hold the entire route string. This size may be larger than the buffer size as the function always returns the size needed to hold the entire buffer. You can pass NULL for this parameter if you are not interested in the return value for routeSpecSize and routeSpec. |
Output
| Name | Type | Description |
|---|---|---|
| routeSpec | NISEBuffer* | The fully specified route path surrounded by delimiting square brackets—if the route exists or is possible. Refer to Route Specification Strings for more information. |
| routeCapability | NISEInt32 | The return value which expresses the capability of finding a valid route between Channel 1 and Channel 2. Refer to the routeCapability table for value descriptions. |
niSE_FindRoute Details
The returned route specification contains the route specification, and the route capability indicates whether the route existed, is possible, or is not possible for various reasons.
The route specification string returned from niSE_FindRoute can be passed to other NI Switch Executive API functions (such as niSE_Connect, niSE_Disconnect, and niSE_ConnectAndDisconnect) that use route specification strings.
To dynamically allocate space for the routeSpec buffer, call niSE_FindRoute twice. The first call should specify a routeSpecSize of 0 and then use the returned routeSpecSize to allocate the correct buffer size.
routeCapability
routeCapability may be any one of the following:
| Value | Name | Description |
|---|---|---|
| 1 | NISE_VAL_PATH_AVAILABLE | A path between channel 1 and channel 2 is available. The route specification parameter returns a string describing the available path. |
| 2 | NISE_VAL_PATH_EXISTS | A path between channel 1 and channel 2 already exists. The route specification parameter returns a string describing the existing path. |
| 3 | NISE_VAL_PATH_UNSUPPORTED | There is no potential path between channel 1 and channel 2 given the current configuration. |
| 4 | NISE_VAL_RSRC_IN_USE | There is a potential path between channel 1 and channel 2, although a resource needed to complete the path is already in use. |
| 5 | NISE_VAL_EXCLUSION_CONFLICT | Channel 1 and channel 2 cannot be connected because their connection would result in an exclusion violation. |
| 6 | NISE_VAL_CHANNEL_NOT_AVAILABLE | One of the channels is not useable as an endpoint channel. Make sure that it is not marked as a reserved for routing. |
| 7 | NISE_VAL_CHANNELS_HARDWIRED | The two channels reside on the same hardwire. An implicit path already exists. |