Physical Address
304 North Cardinal St.
Dorchester Center, MA 02124
ISO/IEC 29341-9-2 — UPnP AV Device Service v1
AV Device Service Specification
ISO/IEC 29341-9-2 defines the AV Device Service, a generic service template that standardizes the state variable model, action signatures, and eventing behavior for UPnP AV devices. While Part 9-1 defines the device template (what a device is), Part 9-2 defines the service template (what a service does). This standard provides the foundational service framework that ContentDirectory, ConnectionManager, AVTransport, and RenderingControl services build upon, ensuring consistent behavior across all AV services.
The service specification introduces formal definitions for state variables (typed data that represents the service state), actions (operations that modify or query the service state), and event notifications (asynchronous updates when state changes occur). It establishes the XML service description schema that all AV services must publish, enabling Control Points to dynamically discover each service’s capabilities, actions, and state variables at runtime.
1. Overview of AV Device Service Architecture
The AV Device Service architecture defines state variables in two categories: moderated and non-moderated. Moderated state variables send event notifications at a maximum rate (e.g., 200 ms minimum interval), while non-moderated variables send events immediately on every change. For AV services, high-frequency variables like AVTransport’s RelativeTimePosition and AbsoluteTimePosition are moderated to prevent event storms, while connection-state variables like AVTransportURI are non-moderated because they change infrequently.
Each service action is defined with its input arguments, output arguments, and possible error codes. The service description schema uses XML to declare these elements, with each argument referencing a state variable that defines its data type (string, ui4, i4, boolean, bin.base64, or custom data types defined by the AV specification). Custom data types include A_ARG_TYPE_ProtocolInfo (a comma-delimited format string describing streaming protocols and content formats) and A_ARG_TYPE_ObjectID (a string identifier for content directory items and containers).
Key Parameters
| Service Feature | Mandatory | Optional |
|---|---|---|
| Get actions (e.g., GetTransportInfo) | Yes | – |
| Set actions (e.g., SetAVTransportURI) | Yes | – |
| LastChange state variable | Yes | – |
| Event moderation (<200ms interval) | Yes | – |
| Error code 701-707 reporting | Yes | – |
| A_ARG_TYPE_SeekMode | – | Required if Seek() is supported |
| A_ARG_TYPE_PlayMode | – | Required if PlayMode != NORMAL |
Implement the LastChange state variable even if your Control Point does not use it. Many third-party Control Points depend on LastChange for polling-based synchronization instead of subscribing to individual event variables.
Never modify a state variable without sending a corresponding event notification. Inconsistent state between the service and subscribed Control Points is a common source of interoperability bugs.
Using the moderated event model for position-related state variables (RelativeTimePosition, AbsoluteTimePosition) reduces network traffic by up to 95% compared to non-moderated events in high-update-rate scenarios.
Failing to implement proper mutex locking around transport state transitions can cause the service to enter an invalid state when two Control Points simultaneously call Play() and Stop().
2. Service State Variables and Actions
The AV Device Service specification defines a comprehensive set of state variable data types. The standard UPnP data types form the foundation: ui4 (unsigned 32-bit integer) for counters and flags, string for names and identifiers, boolean for binary states, and bin.base64 for binary data. AV-specific extensions include: A_ARG_TYPE_SeekMode (enumeration: TRACK_NR, ABS_TIME, REL_TIME, etc.), A_ARG_TYPE_PlayMode (enumeration: NORMAL, SHUFFLE, REPEAT_ONE, REPEAT_ALL, RANDOM), and A_ARG_TYPE_TransportState (enumeration: STOPPED, PAUSED_PLAYBACK, PLAYING, TRANSITIONING, NO_MEDIA_PRESENT).
Service actions follow a naming convention that reflects their function: Get actions (query state, no side effects), Set actions (modify state, side effects), and operational actions like Browse, Search, Next, Previous. Each action must declare exactly which state variables it modifies and which event notifications it triggers. The service description includes a “service control protocol” section that documents the sequence constraints — for example, SetAVTransportURI must be called before Play in the normal playback flow.
Error handling is standardized through a set of predefined UPnP error codes plus AV-specific codes. Common errors include 701 (transition not available), 702 (no contents), 703 (read error), 704 (format not supported), 705 (illegal seek target), 706 (invalid play mode), and 707 (resource not found). Implementing proper error reporting is critical because Control Points depend on error codes to provide meaningful feedback to users and to implement retry logic.
Using the moderated event model for position-related state variables (RelativeTimePosition, AbsoluteTimePosition) reduces network traffic by up to 95% compared to non-moderated events in high-update-rate scenarios.
Failing to implement proper mutex locking around transport state transitions can cause the service to enter an invalid state when two Control Points simultaneously call Play() and Stop().
3. Deployment Patterns
In practice, the AV Device Service template should be implemented with careful attention to thread safety. UPnP service actions and event notifications are inherently asynchronous — multiple Control Points can invoke actions simultaneously, while internal state changes (e.g., track completion) also trigger events. A state machine implementation with proper mutex locking around state variable updates is essential to prevent race conditions. The standard recommends using a read-write lock pattern: shared read access for Get actions, exclusive write access for Set actions and internal state transitions.
Performance optimization strategies include: (1) batching event notifications — if multiple state variables change within a single action invocation, send a single event notification with all updated values rather than separate events; (2) implementing event key sequencing — each event carries a monotonically increasing event key that allows Control Points to detect missed events; (3) supporting the LastChange state variable (a structured XML fragment encoding all recent state changes) for Control Points that prefer polling over event subscription.
Interoperability testing between different service implementations requires validating: action invocation with valid and invalid arguments, event notification timing under various load conditions, state variable consistency after error conditions, and proper cleanup when a Control Point unsubscribes unexpectedly. The UPnP AV certification test suite includes automated tests for these scenarios, but manual testing with reference Control Points (e.g., Intel AV Media Controller, Platinum UPnP SDK test tools) is recommended before certification.
FAQ
Q: What is the difference between moderated and non-moderated state variables?
A: Moderated variables have a minimum event interval (typically 200ms for AV services), meaning rapid changes are batched into periodic notifications. Non-moderated variables send an event immediately on every change. Position tracking variables are moderated; URI and connection state variables are non-moderated.
A: Moderated variables have a minimum event interval (typically 200ms for AV services), meaning rapid changes are batched into periodic notifications. Non-moderated variables send an event immediately on every change. Position tracking variables are moderated; URI and connection state variables are non-moderated.
Q: How should custom error codes be handled?
A: AV service error codes 701-799 are reserved for AV-specific errors. Vendors can define additional codes in the 800-899 range for proprietary extensions, but these must be documented in the vendor’s UPnP Device Compatibility Statement. Returning an undefined error code causes undefined Control Point behavior.
A: AV service error codes 701-799 are reserved for AV-specific errors. Vendors can define additional codes in the 800-899 range for proprietary extensions, but these must be documented in the vendor’s UPnP Device Compatibility Statement. Returning an undefined error code causes undefined Control Point behavior.
Q: Can an AV service omit the subscription eventing mechanism?
A: No. Event subscription via GENA (General Event Notification Architecture) is mandatory for UPnP services. Without eventing, Control Points cannot detect state changes and must resort to polling, which defeats the purpose of UPnP’s event-driven architecture.
A: No. Event subscription via GENA (General Event Notification Architecture) is mandatory for UPnP services. Without eventing, Control Points cannot detect state changes and must resort to polling, which defeats the purpose of UPnP’s event-driven architecture.
