Connection Functions
Provides various functions for configuring the connection to Google Earth. More...
Functions | |
| BOOL | GE_SoftwareLogging (BOOL on) |
| Enables debug logging of GE SDK internal actions. | |
| BOOL | GE_InitGESDK () |
| Initializes the GE SDK internal components. | |
| int | GE_GetHTTPPort () |
| Returns the current HTTP port number used by the internal GE SDK HTTP server. | |
| BOOL | GE_SetHTTPPort (int HTTPPort) |
| Sets the network port number for the internal GE SDK HTTP server. | |
| STRING | GE_GetHTTPIpAddress () |
| Retrieves the internal GE SDK HTTP server IP Address. | |
| BOOL | GE_SetHTTPIpAddress (STRING HTTPIpAddress) |
| Sets the network link IP address for the internal GE SDK HTTP server. | |
| STRING | GE_GetNetworkLinkName () |
| Retrieves the name of the current instance of the GE SDK NetworkLink. | |
| BOOL | GE_SetNetworkLinkName (STRING NetworkLinkName) |
| Sets the name of the current instance of the GE SDK NetworkLink. | |
| float | GE_GetNetworkLinkRefreshRate () |
| Returns the refresh rate of the network link. | |
| BOOL | GE_SetNetworkLinkRefreshRate (float sec) |
| Sets the network link's periodic refresh rate. | |
| BOOL | GE_SetKMLDocumentName (STRING document_name) |
| Sets the network link's document name. | |
| BOOL | GE_SetExeStartDelay (int seconds) |
| Sets the amount of time that the GE SDK will wait for the Google Earth process to start before creating a connection. | |
| BOOL | GE_IsConnected () |
| Reports the current status of the GE SDK Google Earth connection. | |
| BOOL | GE_Connect () |
| Connects to the Google Earth application. | |
| BOOL | GE_ConnectEx (STRING HTTPIpAddress, int HTTPPort, STRING NetworkLinkName, float NetworkLinkRefreshRate) |
| Connects to the Google Earth application with extended settings. | |
| BOOL | GE_Disconnect () |
| Disconnects from Google Earth and stops the GE SDK internal HTTP server. | |
Detailed Description
Provides various functions for configuring the connection to Google Earth.
The Google Earth SDK utilizes a network link to import data into Google Earth. The network link consists of an internal HTTP server that resides in the DLL of the GE SDK. When a connection to Google Earth is made, a network link with a unique name is created under Temporary Places and maintains all the KML objects imported by the GE SDK (see Figure below).
The network link is made unique by its name, HTTP IP address, and HTTP port number. In the above figure, the network link is named "My_Net_Link" and contains a list of KML objects under its "Placemarks" document. The network link contains two components: the network link and the network link updater. The network link updater manages the data through the client-side HTTP link to the GE SDK, while the network link contains the actual KML data present in the Google Earth environment. The network link is refreshed periodically (500 milliseconds by default) and updates are sourced from the GE SDK host application. Changes made to KML objects in Google Earth will occur at this defined frequency.
When an external application imports KML objects into Google Earth using the GE SDK, the data is maintained within Google Earth and the GE SDK. However, the KML objects collection within the GE SDK host application will be lost when the host application closes. To avoid this the GE_Disconnect() function must be called before closing. This will gracefully disconnect the GE SDK network link and allow a clean reconnect when the host application is restarted.
Function Documentation
| BOOL GE_SoftwareLogging | ( | BOOL | on | ) |
Enables debug logging of GE SDK internal actions.
Enable logging to add GE SDK debugging to the host application's software environment. Software logging is disabled by default.
- Note:
- This function must be called first (before GE_InitGESDK()) to enable logging.
- Returns:
- TRUE if initialization was successful; FALSE otherwise
| BOOL GE_InitGESDK | ( | ) |
Initializes the GE SDK internal components.
- Returns:
- TRUE if initialization was successful; FALSE otherwise
| int GE_GetHTTPPort | ( | ) |
Returns the current HTTP port number used by the internal GE SDK HTTP server.
- Returns:
- The network port number of the GE SDK HTTP Server; -1 otherwise
| BOOL GE_SetHTTPPort | ( | int | HTTPPort | ) |
Sets the network port number for the internal GE SDK HTTP server.
- Note:
This function can only be called prior to connecting to Google Earth.
- Parameters:
-
HTTPPort The network port number of the GE SDK HTTP Server (default = 1234)
- Returns:
- TRUE if the function executed properly; FALSE otherwise
| STRING GE_GetHTTPIpAddress | ( | ) |
Retrieves the internal GE SDK HTTP server IP Address.
- Returns:
- A string representation of the HTTP server's IP Address; otherwise the empty string ("")
| BOOL GE_SetHTTPIpAddress | ( | STRING | HTTPIpAddress | ) |
Sets the network link IP address for the internal GE SDK HTTP server.
- Note:
The function can only be called prior to connecting to Google Earth.
- Parameters:
-
HTTPIpAddress The IP Address of the GE SDK HTTP Server. By default this is the local host (127.0.0.1)
- Returns:
- TRUE if the function executed properly; FALSE otherwise
| STRING GE_GetNetworkLinkName | ( | ) |
Retrieves the name of the current instance of the GE SDK NetworkLink.
- Returns:
- The NetworkLink name; otherwise the empty string ("")
| BOOL GE_SetNetworkLinkName | ( | STRING | NetworkLinkName | ) |
Sets the name of the current instance of the GE SDK NetworkLink.
- Note:
The function can only be called prior to connecting to Google Earth.
- Parameters:
-
NetworkLinkName The network link name
- Returns:
- TRUE if the function executed properly; FALSE otherwise
| float GE_GetNetworkLinkRefreshRate | ( | ) |
Returns the refresh rate of the network link.
- Returns:
- The network link refresh rate in seconds; BAD_DOUBLE otherwise
| BOOL GE_SetNetworkLinkRefreshRate | ( | float | sec | ) |
Sets the network link's periodic refresh rate.
- Note:
The function can only be called prior to connecting to Google Earth.
- Parameters:
-
sec The duration between network link updates in decimal seconds
- Returns:
- TRUE if the function executed properly; FALSE otherwise
| BOOL GE_SetKMLDocumentName | ( | STRING | document_name | ) |
Sets the network link's document name.
This is the name of the document group that contains all the KML objects maintained by the current GE SDK instance. For example, in Figure 1 the document name is "Placemarks".
- Parameters:
-
document_name The name to be applied to the network link document
- Returns:
- TRUE if the function executed properly; FALSE otherwise
| BOOL GE_SetExeStartDelay | ( | int | seconds | ) |
Sets the amount of time that the GE SDK will wait for the Google Earth process to start before creating a connection.
Since the time for Google Earth initialization is dependent upon the computer hardware which it runs on, a certain delay is necessary before the GE SDK performs its connection and starts its internal HTTP server. This routine provides a means to adjust this delay. The default delay is 5 seconds.
- Parameters:
-
seconds The delay (in seconds) to wait for the Google Earth process to start (default = 5)
- Returns:
- TRUE if the function executed properly; FALSE otherwise
| BOOL GE_IsConnected | ( | ) |
Reports the current status of the GE SDK Google Earth connection.
When connected to Google Earth, the GE SDK internal HTTP Server is active.
- Returns:
- TRUE if the GE SDK is connected to Google Earth; FALSE otherwise
| BOOL GE_Connect | ( | ) |
Connects to the Google Earth application.
When called, this function starts the GE SDK internal HTTP server and establishes communication with Google Earth via the predefined network link. If Google Earth is not running, this function will start it. A certain amount of delay will occur while the connection is being established. If a known network link already exists in Google Earth's Temporary Places, then the GE SDK will resume the connection.
- Returns:
- TRUE if the connection to Google Earth was successfully made; FALSE otherwise
| BOOL GE_ConnectEx | ( | STRING | HTTPIpAddress, | |
| int | HTTPPort, | |||
| STRING | NetworkLinkName, | |||
| float | NetworkLinkRefreshRate | |||
| ) |
Connects to the Google Earth application with extended settings.
When called, this function starts the GE SDK internal HTTP server and establishes communication with Google Earth via the predefined network link. If Google Earth is not running, this function will start it. A certain amount of delay will occur while the connection is being established. If a known network link already exists in Google Earth's Temporary Places, then the GE SDK will resume the connection.
- Parameters:
-
HTTPIpAddress The IP Address of the GE SDK HTTP Server. By default this is the local host (127.0.0.1) HTTPPort The network port number of the GE SDK HTTP Server (default = 1234) NetworkLinkName The network link name NetworkLinkRefreshRate The duration between network link updates in decimal seconds
- Returns:
- TRUE if the connection to Google Earth was successfully made; FALSE otherwise
| BOOL GE_Disconnect | ( | ) |
Disconnects from Google Earth and stops the GE SDK internal HTTP server.
- Note:
The GE SDK internal collection of KML objects added to Google Earth will be saved every time GE_Disconnect is called. Calling GE_Disconnect should be a routine practice when applications close, otherwise the link to all added KML objects will be lost when the application restarts.
- Returns:
- TRUE if the connection to Google Earth was successfully terminated; FALSE otherwise
