SimConnect_Open
The SimConnect_Open function is used to send a request to the Microsoft Flight Simulator server to open up communications with a new client.
Syntax
HRESULT SimConnect_Open(
HANDLE* phSimConnect,
LPCSTR szName,
HWND hWnd,
DWORD UserEventWin32,
HANDLE hEventHandle,
DWORD ConfigIndex
);
Parameters
| Parameter | Description | Type |
|---|---|---|
| phSimConnect | Pointer to a handle to a SimConnect object. | Integer |
| szName | Pointer to a null-terminated string containing an appropriate name for the client program. | Integer |
| hWnd | Handle to a Windows object. Set this to NULL if the handle is not being used. UserEventWin32 | Integer |
| UserEventWin32 | Code number that the client can specify. Set this to 0 if it is not being used. | Integer |
| hEventHandle | A Windows Event handle. A client can be written to respond to Windows Events, rather than use a polling and callback system, which can be a more efficient process if the client does not have to respond very frequently to changes in data in Microsoft Flight Simulator. | Integer |
| ConfigIndex | The configuration index. The SimConnect.cfg file can contain a number of configurations, identified in sections with the [SimConnect] or [SimConnect.N] titles. Setting this configuration index indicates which configuration settings to use for this SimConnect client. This is useful for applications that communicate with a number of different machines that are running Microsoft Flight Simulator. The default configuration index is zero (matching a [SimConnect] entry in a SimConnect.cfg file). Note the E_INVALIDARG return value. | Integer |
Return Values
The function returns an HRESULT. Possible values include, but are not limited to, those in the following table.
| Return value | Description |
|---|---|
| S_OK | The function succeeded. |
| E_FAIL | The function failed. |
| E_INVALIDARG | A SimConnect section in the SimConnect.cfg file did not contain the config index requested in the parameters. |
Example
HRESULT hr; HANDLE hSimConnect = NULL;
hr = SimConnect_Open(&hSimConnect, "Your Application Name", NULL, 0, 0, SIMCONNECT_OPEN_CONFIGINDEX_LOCAL);
Remarks
Most client applications will have one SimConnect_Open call, and one corresponding SimConnect_Close call. However in some applications, multiplayer in particular, multiple SimConnect_Open calls may be necessary, in which case an array or list of handles will need to be maintained, and closed appropriately.
A client can optionally examine the SIMCOMMENT_RECV_OPEN structure that is returned after a call to SimConnect_Open. This structure gives versioning and build information that should be useful when multiple versions of SimConnect and multiple versions of Microsoft Flight Simulator that support it, are available.
If a remote client successfully establishes a link with Flight Simulator, but at some later time the network connection is lost, SimConnect functions will return the NTSTATUS error STATUS_REMOTE_DISCONNECT (0xC000013CL).
The SIMCONNECT_EXCEPTION_VERSION_MISMATCH exception will be returned if a versioning error has occurred, typically when a client built on a newer version of the SimConnect client dll attempts to work with an older version of the SimConnect server. If this exception is received the number 4 is returned in the dwIndex parameter of the SIMCONNECT_RECV_EXCEPTION structure.