SimConnect

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).