TTMSFMXNativeMultipeerConnectivity
Usage
The TMSFMXNativeMultipeerConnectivity component
Methods
| Methods name | Description |
|---|---|
| SearchForPeers | Searches and displays available peers configured with the same ServiceType property. |
| SendResource(AFile: String; APeer: MCPeerID) | Sends a resource file to a specific peer. |
| SendResourceToAllPeers(AFile: String) | Sends a resource file to all peers. |
| SendString(AValue: String; APeer: MCPeerID) | Sends a String to a specific peer. |
| SendStringToAllPeers(AValue: String); overload | Sends a String to all peers. |
| SendInteger(AValue: Integer; APeer: MCPeerID) | Sends an Integer to a specific peer. |
| SendIntegerToAllPeers(AValue: Integer) | Sends an Integer to all peers. |
| SendBoolean(AValue: Boolean; APeer: MCPeerID) | Sends a Boolean to a specific peer. |
| SendBooleanToAllPeers(AValue: Boolean) | Sends a Boolean to all peers. |
| SendDouble(AValue: Double; APeer: MCPeerID) | Sends a Double to a specific peer. |
| SendDoubleToAllPeers(AValue: Double) | Sends a Double to all peers. |
| SendObject(AValue: TMemoryStream; APeer: MCPeerID) | Sends a memory stream object to a specific peer. |
| SendObjectToAllPeers(AValue: TMemoryStream) | Sends a memory stream object to all peers. |
| PeerCount: Integer | The number of connected peers. |
Public Properties
| Properties name | Description |
|---|---|
| AdvertiserAssistant | Assistant that handles users’ responses and presents incoming peer connections through the BrowserViewController. |
| BrowserViewController | The controller that is used to display a list of available peers, limited to the MinimumNumberOfPeers and the MaximumNumberOfPeers properties. Already connected peers are also displayed in this window. The BrowserViewController is shown when calling SearchForPeers. |
| Peers[Index: Integer] | |
| PeerDisplayNames[Index: Integer] | Returns the name of the connected peer at a specific index. |
| PeerID | Your own created peer ID used to connect to other peers. The display name of the peer can be set at designtime or runtime with the MyPeerID property when the MyPeerIDKind property is set to pidkCustom. By default the peer is configured to use the name of the device. |
| Session | The current session, with a session service type. The session name can be set with the property ServiceType. |
Properties
| Properties name | Description |
|---|---|
| MaximumNumberOfPeers | The maximum number of allowed peers in a session, which is 8 by default. |
| MinimumNumberOfPeers | The minimum number of required peers in a session, which is 2 by default. This number already incorporates your own peer connection. |
| MyPeerID | The name of your own peer ID, used to display to other peers when establishing a connection. The display name of the peer is set to the device name by default but can be changed through this property after setting the MyPeerIDKind property to pidkCustom. |
| MyPeerIDKind | The kind of displayname your own peer will have when establishing a connection with other peers. More information can be found at the MyPeerID property explanation. |
| SendDataMode | The mode used to send data, such as strings, integers, booleans and memorystreams reliable or unreliable. The reliable method is slower than the unreliable method but additionally verifies if the sent data is received correctly. |
| ServiceType | The type of service the peer is offering when establishing a connection to other peers. This property is used to create a session. Only peers with the same ServiceType property can connect to eachother. |
Events
| Events name | Description |
|---|---|
| OnBrowserViewControllerDidFinish | Event called when the BrowserViewController finished searching and connecting peers. When the MaximumNumberOfPeers has been reached, the BrowserViewController will automatically dismiss and call this event. This event is also called when clicking the Done button. |
| OnBrowserViewControllerWasCancelled | Event called when the cancel button of the BrowserViewController has been clicked. |
| OnDidChangeState | Event called when the state of one of the connected peers has changed. The state of the peer can be disconnected, connecting or connected. This event can be called mulitple times with different peer and state parameters. |
| OnDidReceiveBoolean | Event called when a Boolean is received from a specific peer. |
| OnDidReceiveDouble | Event called when a Double is received from a specific peer. |
| OnDidReceiveInteger | Event called when an Integer is received from a specific peer. |
| OnDidReceiveObject | Event called when a memorystream objec is received from a specific peer. |
| OnDidReceiveResource | Event called when a resource file is completely received. Through this event, the automatically created temporary file will be saved in the Documents folder of the application. This behavior can be changed by changing the value of the AllowSave parameter. The filename that is being used to save the temporary file in the documents folder can be overridden by changing the ASaveFileName parameter. |
| OnDidReceiveString | Event called when a String is received from a specific peer. |
| OnDidSendResource | Event called when a resource file is sent and has succesfully reached the peer it was sent to. |
| OnDidStartReceivingResource | Event called when a resource will be received from a specific peer. |
| OnError | Event called when an error occurred during sending or receiving data and resource files. |
| OnReceiveResource | Event called multiple times with the progress of the resource file that is being received, sent by a specific peer. Trough this event, the AProgress parameter can be used to indicate the receiving progress. The ACancel Boolean parameter can be used to cancel receiving a resource file. |
| OnSendResource | Event called multiple times with the progress of the resource file that is being sent to a specific peer. Through this event, the AProgress parameter can be used to indicate the sending progress. The ACancel Boolean parameter can be used to cancel sending a resource file. |
Managing peers
Before data and/or resource files can be sent to single peer or multiple peers, the peer(s) must first be connected to a session based on the the ServiceType property. The ServiceType property is preset with “tms-peertopeer” and can be modified at designtime. This property identifies your session as an entry point for other peers. A session with a different ServiceType property, will not be able to identify the peers managed by the session that is created with “tms-peertopeer”.
Each session has it’s own peer id, to identify itself to other peers.
By default, the PeerID instance is assigned a displayname. The displayname is set to the device name by default, but can be changed to a custom value, by setting the MyPeerIDKind to pidkCustom and setting the MyPeerID property to a value of choice.
After properly determining the ServiceType and the MyPeerID properties, the application is ready to create the session and browse for other peers. Peers can be searched by calling the following code:
SearchForPeers will automatically popup the BrowserViewController instance, which will handle the connection of all peers within a session. Tap on the peers that are available for a connection, and the BrowserViewController will handle and maintain the connection.
When a peer is connected, the application is ready to send data or resource files to one or multiple peers. To know the connected peers, you can use the PeerCount function and the Peers property to retrieve a connected peer by specifying an index. To find out the names of the connected peers and display them in a list, you can use the PeerDisplayNames property with the same approach.
The PeerCount function, Peers and PeerDisplayNames properties will automatically update as the connections are automatically managed by the TTMSFMXNativeMultipeerConnectivity component. To know the state of one or multiple peers, you can use the OnDidChangeState event, that will allow you to monitor the state of each peer, whether it is disconnected, connecting or connected.
Sending Data
To send data, you can use one of the multiple methods specified and explained in the methods table. Below is a sample to send a String to all connected peers.
If you wish to send a Boolean to a specific peer you can use the code below:
var
peer: MCPeerID;
begin
peer := TMSFMXNativeMultipeerConnectivity1.Peers[0];
TMSFMXNativeMultipeerConnectivity1.SendBoolean(true, peer);
end;
Receiving Data
Receiving data is done through one of the various events. Each Send* method has a equivalent for receiving that specific type of data. Sending a string can be received with the OnDidReceiveString, while sending a Boolean can be received by implementing the OnDidReceiveBoolean. Below is a sample that displays the String value with the Peer displayname as the text of a label.
procedure TForm1.TMSFMXNativeMultipeerConnectivity1DidReceiveString(
Sender: TObject; AValue: string;
APeer: TTMSFMXNativeMultipeerConnectivityPeer);
begin
Label1.Text := 'Received ' + AValue + ' from ' + APeer.DisplayName;
end;
Sending and Receiving Files
Sending and Receiving files is done with the same approach as sending and receiving data, with the possibility to cancel and monitor progress of a send and/or receive operation. Various events are published to manage this operation. More information can be found at the Method & Events table.