The ProximityDevice class uses publish/subscribe semantics and is useful for advertising and receiving small blocks of data. For larger amounts of data, or for persistent communications, use the PeerFinder and StreamSocket classes. For Windows Store app, publications and subscriptions are active only if the calling app is in the foreground.

Important

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.

Remarks

If your computer supports Proximity and has an NFC device installed, which is commonly the case, then the GetDefault method will return the device that supports NFC. You can also determine whether your computer has an NFC device installed by querying the device information for the property "{FB3842CD-9E2A-4F83-8FCC-4B0761139AE9} 2". In the DeviceInformation.Properties object returned from the query the value for the "{FB3842CD-9E2A-4F83-8FCC-4B0761139AE9} 2" key contains and array of strings that describe the capabilities of the proximity device. If one of the strings is "StandardNfc", then the device supports NFC protocols such as NDEF. For more information on how to query for the properties of a device, see How to retrieve additional properties for a device or PnP object.

Methods

FromId(String)FromId(String)FromId(String)FromId(String)

Creates an instance of a ProximityDevice class and activates the specified proximity device interface.

public : static ProximityDevice FromId(PlatForm::String deviceId)public static ProximityDevice FromId(String deviceId)Public Static Function FromId(deviceId As String) As ProximityDevice// You can use this method in JavaScript.

Remarks

If your computer supports Proximity and has an NFC device installed, which is commonly the case, then the GetDefault method will return the device that supports NFC. You can also determine whether your computer has an NFC device installed by querying the device information for the property "{FB3842CD-9E2A-4F83-8FCC-4B0761139AE9} 2". In the DeviceInformation.Properties object returned from the query the value for the "{FB3842CD-9E2A-4F83-8FCC-4B0761139AE9} 2" key contains and array of strings that describe the capabilities of the proximity device. If one of the strings is "StandardNfc", then the device supports NFC protocols such as NDEF. For more information on how to query for the properties of a device, see How to retrieve additional properties for a device or PnP object.

Publishes a message that contains binary data to subscribers of the specified message type.

public : long PublishBinaryMessage(PlatForm::String messageType, IBuffer message)public long PublishBinaryMessage(String messageType, IBuffer message)Public Function PublishBinaryMessage(messageType As String, message As IBuffer) As long// You can use this method in JavaScript.

You can use the PublishMessage method to publish a text message to a proximate computer. You can use the PublishUriMessage method to publish a Uniform Resource Identifier (URI) to a proximate computer.

Important

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.

Message Types

You use the messageType parameter to supply an identifier that uniquely identifies the published message, and also defines the meaning of the message and the intended subscriber audience.

Message type values are case-sensitive strings that consist of two parts: the protocol and the subtype. The protocol is first, followed by a dot (.) and then the subtype. The subtype is a string of alphanumeric characters and any of the valid URI characters as defined by RFC 3986: - . _~ : / ? # [ ] @ ! $ & ‘ ( ) * + , ; = %. The subtype cannot exceed a length of 250 characters. The following table shows the supported values for the protocol part of the message type.

ProtocolWindowsThe message contains binary data.WindowsUriThe message data contains a UTF-16LE encoded string that is a Uniform Resource Identifier (URI).
Windows will always handle "WindowsUri" messages by prompting the user to view a received URI that in the Windows default app that handles a specific URI protocol, for example, http:// URIs open in the default web browser. Windows will open a URI in the default app even if another app is also subscribed to "WindowsUri".
Instead of calling the PublishBinaryMessage method with this protocol, use the PublishUriMessage method.
If you publish a Uri to a computer that is not running Windows, the Uri is automatically formatted based on the proximity technology that your computer supports. For example, if your computer uses NFC hardware for proximity, then the Uri is formatted as an NDEF URI record.
If you are subscribing for a "WindowsUri" message and your Windows computer receives a message formatted for the proximity technology that your computer supports, Windows reads the formatted message and returns only the Uri as the message content.WindowsMimeThe message data is of a specific mime type. For example, if the message data is a jpeg image, the message type is "WindowsMime.image/jpeg".
Windows will always handle "WindowsMime" messages by prompting the user to view the mime content that was received, even if an app is also subscribed for the mime content.
If you publish a "WindowsMime" message to a computer that is not running Windows, the message content is automatically formatted based on the proximity technology that your computer supports. For example, if your computer uses NFC hardware for proximity, then the message content is formatted as an NDEF Mime record.
If you are publishing a "WindowsMime" message, you must always include the mime type. If you are subscribing to a "WindowsMime" message, you can use "WindowsMime" without specifying the mime type to subscribe for all mime types. If you subscribe to a specific mime type and your Windows computer receives a message formatted for the proximity technology that your computer supports, Windows reads the formatted message and returns only the mime content as the message content. If you subscribe for all mime types, the first 256 bytes received is the ASCII mime type string, and the remaining bytes are the mime content.Windows:WriteTagThis is the same as the Windows protocol, except that the content is intended to be written to a static tag. The message is not transmitted to any device except a writable static tag. This protocol is only valid for publications. An example of this protocol is "Windows:WriteTag.SampleSubtype".WindowsUri:WriteTagThis is the same as the WindowsUri protocol, except that the content is intended to be written to a static tag. The message is not transmitted to any device except a writable static tag. This protocol is only valid for publications.WindowsMime:WriteTagThis is the same as the WindowsMime protocol, except that the content is intended to be written to a static tag. The message is not transmitted to any device except a writable static tag. This protocol is only valid for publications. An example of this protocol is "WindowsMime:WriteTag.image/jpeg".LaunchApp:WriteTagWrite a tag that can be used to launch a specific app with optional launch parameters. If you publish a LaunchApp:WriteTag message to a tag the result when that tag is tapped to a computer is the same as calling the PeerFinder.Start method and passing your launch parameters. The message must be a UTF-16LE encoded string where the values are delimited by tab characters or null values in the following form:
text
<launch arguments>[tab]<app platform 1>[tab]<app name 1>...[tab]<app platform N>[tab]<app name N>
The launch arguments are optional. The message can omit them:
text
<app platform 1>[tab]<app name 1>...[tab]<app platform N>[tab]<app name N>
You must specify at least one app platform and app name. The app platform for a Windows 8 computer is Windows. The format of the proximity app Id is <package family name>!<app Id>. You can get the package family name from the Windows.ApplicationModel.Package.Current.Id.FamilyName property. You must copy the app Id value from the Id attribute of the Application element in the package manifest for your app. An example of this message is "user=default\tWindows\tExample.Proximity.JS_8wekyb3d8bbwe!Proximity.App".
You can also support other app platforms. For more information, see AlternateIdentities. subscribing for this message protocol, if a writeable tag is brought in to proximity, a proximity message is received that contains an int32 (little endian) indicating the maximum writeable size of the tag. This protocol is only valid for subscriptions.Pairing:BluetoothWindows subscribes to this message type to complete a Bluetooth pairing using proximity. This protocol is not intended to be uses in apps.NDEFThe message contents are properly formatted NDEF records. The underlying type of the content for a publication using NDEF as the message type is contained in the NDEF records. A subscription for the NDEF type subscribes to all NDEF formatted messages.NDEF:extThe message data is application defined NDEF records (TNF field value of 0x04).
This protocol will launch a properly configured application to handle these events if there is no running application already subscribing to these events. To designate an app to handle a particular protocol using NDEF:ext, you must add a Protocol tag to the app manifest to specify the URI that will launch the app. The appropriate manifest syntax is demonstrated in the following example.
xml
<Extensions>
<Extension Category="windows.protocol">
<Protocol Name="contoso.com+testapp" />
</Extension>
</Extensions>
> [!NOTE]
> The URI format used in the app manifest is slightly different from the URI format used on the NFC tag, in that the manifest URI uses a '+ ' character rather than a ': ' character. The URI on the NFC tag that activates the app with the manifest sample above is contoso.com:testapp.NDEF:MIMEThe message data is a properly formatted NDEF mime message (TNF field value of 0x02). For example, "NDEF:MIME.image/jpeg". This protocol only applies to subscriptions, when publishing NDEF content, use NDEF.NDEF:URIThe message data is a properly formatted NDEF message of a type defined by a URI namespace (TNF field value of 0x03).This protocol only applies to subscriptions, when publishing NDEF content, use NDEF. This means that the data format is identified by the specified URI. An example of this protocol is "NDEF:URI.http://contoso.com/sometype".NDEF:wktThe message data is a properly formatted NDEF message of a type defined by the NFC forum (TNF field value of 0x01).An example of this type is "NDEF:wkt.U" for the well known type of URI. This protocol only applies to subscriptions, when publishing NDEF content, use NDEF.NDEF:WriteTagThe message data should be written to an NFC forum standard static tag. The message data must be in a proper NDEF format. This protocol is only valid for publications.NDEF:UnknownThe message data is an untyped NDEF message (TNF field value of 0x05).This protocol only applies to subscriptions, when publishing NDEF content, use NDEF.

Publishes a message that contains binary data to subscribers of the specified message type. The specified handler is called when the message has been transmitted.

public : long PublishBinaryMessage(PlatForm::String messageType, IBuffer message, MessageTransmittedHandler messageTransmittedHandler)public long PublishBinaryMessage(String messageType, IBuffer message, MessageTransmittedHandler messageTransmittedHandler)Public Function PublishBinaryMessage(messageType As String, message As IBuffer, messageTransmittedHandler As MessageTransmittedHandler) As long// You can use this method in JavaScript.

You can use the PublishMessage method to publish a text message to a proximate computer. You can use the PublishUriMessage method to publish a Uniform Resource Identifier (URI) to a proximate computer.

Important

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.

public : long PublishMessage(PlatForm::String messageType, PlatForm::String message)public long PublishMessage(String messageType, String message)Public Function PublishMessage(messageType As String, message As String) As long// You can use this method in JavaScript.

Parameters

messageType

PlatForm::StringStringStringString

The type of message to deliver to subscribers.

message

PlatForm::StringStringStringString

The message to deliver to subscribers.

Returns

longlonglonglong

A unique publication ID for the published message. Pass this value to the StopPublishingMessage method to stop publishing the message.

Additional features and requirements

Device family

Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)

Messages are delivered to all applications that have subscribed to the message type (as indicated by the messageType parameter). Message type values are case-sensitive strings that consist of two parts: the protocol and the subtype. The protocol is first, followed by a dot (.) and then the subtype. For the PublishMessage method, the protocol must always be "Windows.". The subtype is a string of alphanumeric characters and the following additional characters: . ( ) + , - : = @ ; $ _ ! * ’. The subtype cannot exceed a length of 250 characters.

To publish messages by using another message type, like “WindowsMime.” or “NDEF:WriteTag”, you must use the PublishBinaryMessage method.

You can use the PublishUriMessage method to publish a Uniform Resource Identifier (URI) to a proximate computer.

Messages are converted to UTF-8 characters before they're transmitted.

For Windows Store app, publications and subscriptions are active only if the calling app is in the foreground.

Important

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.

Publishes a message to subscribers of the specified message type. The specified handler is called when the message has been transmitted.

public : long PublishMessage(PlatForm::String messageType, PlatForm::String message, MessageTransmittedHandler messageTransmittedHandler)public long PublishMessage(String messageType, String message, MessageTransmittedHandler messageTransmittedHandler)Public Function PublishMessage(messageType As String, message As String, messageTransmittedHandler As MessageTransmittedHandler) As long// You can use this method in JavaScript.

Messages are delivered to all applications that have subscribed to the message type (as indicated by the messageType parameter). Message type values are case-sensitive strings that consist of two parts: the protocol and the subtype. The protocol is first, followed by a dot (.) and then the subtype. For the PublishMessage method, the protocol must always be "Windows.". The subtype is a string of alphanumeric characters and the following additional characters: . ( ) + , - : = @ ; $ _ ! * ’. The subtype cannot exceed a length of 250 characters.

To publish messages by using another message type, like “WindowsMime.” or “NDEF:WriteTag”, you must use the PublishBinaryMessage method.

You can use the PublishUriMessage method to publish a Uniform Resource Identifier (URI) to a proximate computer.

Messages are converted to UTF-8 characters before they're transmitted.

For Windows Store app, publications and subscriptions are active only if the calling app is in the foreground.

Important

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.

Unlike the other publish methods for a proximity device, URI publishing is handled by the default protocol handler for the URI. A subscription to a URI message publication is not required. You can receive URI messages by registering a default handler for a URI protocol such as the HTTP protocol.

The PackageFamilyName value of the sending application is automatically sent along with the URI. If no handler is registered for the protocol of a URI, the PackageFamilyName value of the sending application is used to direct the receiving application to the application store.

You can use the PublishMessage method to publish a text message to a proximate computer. You can use the PublishBinaryMessage method to publish non-text messages or messages that conform to the NDEF messaging standard.

Important

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.

Publishes a Uniform Resource Identifier (URI) to a proximate device. The specified handler is called when the message has been transmitted.

public : long PublishUriMessage(Uri message, MessageTransmittedHandler messageTransmittedHandler)public long PublishUriMessage(Uri message, MessageTransmittedHandler messageTransmittedHandler)Public Function PublishUriMessage(message As Uri, messageTransmittedHandler As MessageTransmittedHandler) As long// You can use this method in JavaScript.

Unlike the other publish methods for a proximity device, URI publishing is handled by the default protocol handler for the URI. A subscription to a URI message publication is not required. You can receive URI messages by registering a default handler for a URI protocol such as the HTTP protocol.

The PackageFamilyName value of the sending application is automatically sent along with the URI. If no handler is registered for the protocol of a URI, the PackageFamilyName value of the sending application is used to direct the receiving application to the application store.

You can use the PublishMessage method to publish a text message to a proximate computer. You can use the PublishBinaryMessage method to publish non-text messages or messages that conform to the NDEF messaging standard.

Important

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.

public : void StopPublishingMessage(long messageId)public void StopPublishingMessage(Int64 messageId)Public Function StopPublishingMessage(messageId As Int64) As void// You can use this method in JavaScript.

Parameters

messageId

longInt64Int64Int64

The publication ID for the message.

Additional features and requirements

Device family

Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)

public : void StopSubscribingForMessage(long subscriptionId)public void StopSubscribingForMessage(Int64 subscriptionId)Public Function StopSubscribingForMessage(subscriptionId As Int64) As void// You can use this method in JavaScript.

Parameters

subscriptionId

longInt64Int64Int64

The subscription ID for the message.

Additional features and requirements

Device family

Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)

public : long SubscribeForMessage(PlatForm::String messageType, MessageReceivedHandler messageReceivedHandler)public long SubscribeForMessage(String messageType, MessageReceivedHandler messageReceivedHandler)Public Function SubscribeForMessage(messageType As String, messageReceivedHandler As MessageReceivedHandler) As long// You can use this method in JavaScript.

Remarks

After your app calls the SubscribeForMessage method, it will receive messages that are published with the same message type (as indicated by the messageType parameter) from any proximate devices. For details on the different message types, see the remarks in the PublishBinaryMessage(String, IBuffer) reference topic.

Important

The proximity APIs do not provide authentication, encryption, or message integrity. Do not use proximity to exchange user sensitive information such as passwords, financial data, text messages, email, photographs, or government id numbers.