Connecting to Remote Applications Using App Tethering

From RAD Studio
Jump to: navigation, search

Go Up to Using App Tethering

Before the TTetheringAppProfile components of two applications can share actions and data using app tethering, your applications must discover and get paired with each other using their TTetheringManager component, and then their TTetheringAppProfile components must connect.

Configuring Your Adapters

Adapters are classes that provide support for using specific communication systems to discover, pair and exchange data with applications.

RAD Studio provides built-in adapters for Internet Protocol (IP) and Classic Bluetooth technologies. You can also create your own adapters.

Use the AllowedAdapters property of your TTetheringManager to configure the adapters that you want your application to use for app tethering.

Choosing an Approach for Discovering, Pairing, and Connecting to Remote Applications

You can use either of the following approaches to discover and pair applications:

Using groups is simpler, but the manual approach offers more flexibility, and both approaches support password-protected pairing. Choose the approach that better fits your use case; you can also combine both approaches using the same TTetheringManager.

Using Groups to Connect Applications

If you want your applications to automatically discover and pair with each other:

  1. Enter the same string in the Group property of the TTetheringAppProfile component of each application.
  2. Call the AutoConnect method of the TTetheringManager component of each application at run time.

Choose a Group string that is as unique as possible, to prevent your applications from accidentally connecting to third-party applications that happen to use the same Group. For example, you can use a UUID as the Group string.

Note: Third-party applications could still find out your Group and use it intentionally to connect automatically to your applications. If you don't want to allow third-party applications to automatically connect to your applications using app tethering, use a password.

When you call AutoConnect on one of your applications, your application discovers any other application that is also using app tethering, and your application automatically pairs and connects to those discovered applications that contain a TTetheringAppProfile component that is in the same Group as your TTetheringAppProfile component. When AutoConnect finishes, the OnEndAutoConnect event occurs.

Connecting with Remote Applications Manually

If you want to have more control over the discovering and pairing phases of the app tethering connection, you can use the following approach instead:

  1. Call the DiscoverManagers method of your TTetheringManager component of your application to start discovering other applications that use app tethering. When the discovery finishes, the OnEndManagersDiscovery event of your manager occurs.
  2. Read the list of discovered RemoteManagers of your TTetheringManager, and call TTetheringManager.PairManager to pair with those that you want. Each time that you pair your manager with a remote manager, the OnEndProfilesDiscovery event of your manager occurs.
  3. Read the list of discovered RemoteProfiles of your TTetheringManager, and call Connect on your TTetheringAppProfile component to connect to those that you want.

Remote managers and remote profiles are instances of TTetheringManagerInfo and TTetheringProfileInfo, respectively. These classes provide information about an instance of TTetheringManager or TTetheringAppProfile from a remote application. Use this information to determine whether or not to pair or connect with a specific remote manager or profile.

Connecting to Applications Outside Your Subnet

By default, both AutoConnect and DiscoverManagers perform the discovery on the subnet of the local area network (LAN) where the device running your application is.

However, you can use their optional parameter Target to override this behavior, and specify an IP address or subnet:

  • To specify an IP address to search for remote managers, specify that IP address as the Target.
  • To specify a subnet of IP addresses, specify an IP address with a 0 as its fourth number. For example, if you specify "" as the Target, your manager searches the 192.168.4.x subnet for remote managers.
Note: You can not specify wider subnets. For example, "" is not supported.

Using a Password for Pairing

The RTL provides password-based security for app tethering pairing between applications. You can use this password-based system to implement your own security procedure. For example, you can:

  • Make your applications connect automatically when they discover each other, transparently to your users.
  • Let your users manually enter a password in both applications to pair them.

Use the Password property of your manager to specify a password that remote managers must know in order to pair with your manager. When a manager attempts to pair with a password-protected remote manager, the OnRequestManagerPassword event of the local manager occurs, and the local manager must specify the correct password in this event. Otherwise, the pairing fails.

Persisting Pairing Information

When your manager pairs with a remote manager, your manager stores the identifier of the remote manager and a hash that both managers shared during the pairing process. At some point, your managers may lose the connection to each other, for example because they stop being in reach of each other (tethering-wise) for some time. If both managers get back in reach of each other, they can recognize and authenticate each other using the data that they stored during the previous pairing process. This authentication does not require a password, even if a password was necessary during the original pairing process.

By default, managers store the information about which remote managers are paired to them in memory. As a result, your manager can reconnect to a previously-paired remote manager, but only during the same session. If you restart your application, your manager loses its pairing data and cannot reconnect to previously-paired remote managers automatically without using a password again if a password is required.

You can implement a subclass of TTetheringCustomStorage and assign an instance to the AStorage parameter of the OnRequestStorage event of your manager to provide persistence to your manager. Your implementation can store this data in a persistent media, such as a local file.

Note: For two managers to be able to pair to each other after a restart, both managers must be persistent.

The TetheringIniFileStorage code example unit provides an example of implementing a subclass of TTetheringCustomStorage. You can use the TetheringIniFileStorage unit to persist the pairing data of your TTetheringManager component to an INI file.

See Also