Message Subscriptions

A subscription is represented as a unique open handle within the driver. A subscription is made active by opening a handle into the “Subs\” device namespace. The type of the subscription is defined to be everything following the “Subs\” prefix.

A callback on message reception is given through a completed IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE.

A subscription can be temporarily disabled via an IOCTL_NFP_DISABLE.

A subscription can be re-enabled via an IOCTL_NFP_ENABLE.

Handles

A client that wants to subscribe to a message type will first open a new handle to the driver. Handles from prior publications, subscriptions, and so on, cannot be reused. If they are no longer needed, they will be closed by a well-behaved client.

In opening the handle, a client sets the type of the message subscription. This is the same mechanism as used with publishing, except that the type is prefixed with “Subs\” instead of “Pubs\”.

There is no facility to read back the type.

Required Actions

  • The driver MUST parse the protocol component (before the first ‘.’). Any unrecognized protocol MUST complete with STATUS_OBJECT_PATH_NOT_FOUND
  • If the string is not NULL-terminated within the buffer length, the driver MUST complete the IOCTL with STATUS_INVALID_PARAMETER.
  • If the protocol requires a subtype and the subtype component of the string buffer is less than one (1) character or longer than 250 characters, the driver MUST complete the IOCTL with STATUS_INVALID_PARAMETER.
  • If the protocol component of the string buffer is longer than 250 characters, the driver MUST complete the IOCTL with STATUS_INVALID_PARAMETER.
  • The driver MUST interpret the first NULL as the end of the string.
  • The driver MAY recognize the “Pairing:Bluetooth” type for subscriptions.
  • The driver MUST recognize the “WindowsUri” type.
  • The driver MUST recognize the “DeviceArrived” type for subscriptions only.
  • The driver MUST recognize the “DeviceDeparted” type for subscriptions only.
  • The driver MUST recognize the “WindowsMime” type for subscriptions only.
  • The driver MUST recognize the “WindowsMime.” type.
  • If the protocol should only be recognized for subscriptions, and the IOCTL specifies “Pubs\”, the driver MUST complete the IOCTL with STATUS_OBJECT_PATH_NOT_FOUND.
  • If the protocol should only be recognized for publications, and the IOCTL specifies “Subs\”, the driver MUST complete the IOCTL with STATUS_OBJECT_PATH_NOT_FOUND.
  • Some protocols (namespaces) are reserved. Unless explicitly specified in this document, the driver MUST NOT recognize any protocols that begin with:
    "Windows”
    "Device”
    "Pairing”
    "NDEF”
  • Two open handles to the same type MUST represent two distinct entities.
  • If CreateFile succeeds, the handle is now a “subscription handle”, and MUST NOT be changed into any other type of handle.
  • After this IOCTL succeeds, and before the handle is closed, every time a message is received via the proximity technology that matches the type of this subscription then that message’s data MUST be attached to the file handle for delivery to the client.

Unsubscribe

The client will close the subscription handle in order to stop receiving messages. If a client process terminates, the system will close all open file handles on behalf of the client.

Required Actions

When the handle is closed, the driver MUST reclaim all memory used by the subscription:

  • The driver MUST reclaim the type string data.
  • The received queue MUST be purged and reclaimed.
  • Any pended IOCTL MUST be completed with STATUS_CANCELLED.

Malicious Peers

If a malicious peer device attempts a denial of service (DOS) attack via the proximity technology, it’s possible that a client could be unable to drain the “Received” queue fast enough to prevent excessive memory use by the driver.

Required Actions

The driver MUST NOT queue or deliver a given message to the client if that message is received when 50 messages are currently in the “Received” queue (the newest messages are dropped).

Unresponsive or Misbehaving Clients

If a client stops draining the “Received” queue by failing to send the required IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE request for a period of ten to twenty seconds [10-20sec], the driver should assume that the client is gone. Under normal circumstances, clients should refresh their requests well within one second [1s]. Delivering messages that are over twenty seconds [20sec] old would confuse users. If this occurs, the driver should drain the “Received” queue and mark it as NOT capable of holding any messages until the client wakes up and sends the required IRP. Note that this is best implemented without timers, and instead by checking for forward progress at the various steps: IOCTL received, message received, and so on.

Required Actions

The driver MUST remove all messages (and reclaim those resources) from the “Received” queue if the client has not sent a replacement IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE within 10 - 20 seconds of the prior IOCTL completion.

Malformed Messages

The client is likely to drop or ignore all errors (except STATUS_BUFFER_OVERFLOW) returned from IOCTL_NFP_GET_NEXT_SUBSCRIBED_MESSAGE. Therefore, the driver shouldn’t complete these with error conditions merely because a malformed message was received.

Required Actions

  • The driver MUST NOT deliver messages that are larger than the maximum permitted message size to the client.
  • The driver SHOULD NOT deliver zero-length messages to the client.
  • The driver MUST NOT deliver partial messages to subscribers.
  • The driver MUST NOT deliver messages to the client that have failed a strong CRC.

    Note  NFC Forum Certification guarantees this for NFC-enabled NFP providers.

  • The driver MUST use a strongly reliable transport and/or attempt retransmission of messages that fail a strong CRC.

    Note  NFC Forum Certification guarantees this for NFC-enabled NFP providers.

Duplicate Subscriptions

The driver should assume that if the client subscribes for a message type twice, it is because the client wants to receive the message twice when the message is received.

Required Actions

The driver MUST accept and report duplicate subscriptions, even if subscribed by the same client.

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft