App capability declarations
[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]
If your app needs programmatic access to user resources like Pictures, or to devices like a camera, you must declare the appropriate capability. You request access by declaring capabilities in your app's package manifest. You can declare general capabilities by using the Manifest Designer in Microsoft Visual Studio, or you can add them manually—see How to specify capabilities in a package manifest. It is important to know that when customers get your app from the Store, they're notified of all the capabilities that the app declares. So do not use capabilities that your app doesn't need.
This article has capabilities that are separated in four categories described below.
General-use capabilities that apply to most common app scenarios.
Device capabilities that allow your app to access peripheral and internal devices.
Special-use capabilities that require a special company account for submission to the Store to use them. For more info about company accounts, see Account types, locations, and fees.
Note This topic does not apply to Windows Phone. For more information about Windows Phone capabilities, see App capabilities and hardware requirements for Windows Phone 8.
General-use capabilities
General-use capabilities apply to the most common app scenarios.
| Capability scenario | Capability usage |
|---|---|
| Music | The musicLibrary capability provides programmatic access to the user's Music, allowing the app to enumerate and access all files in the library without user interaction. This capability is typically used in jukebox apps that make use of the entire Music library. The file picker provides a robust UI mechanism that lets users open files for use with an app. Declare the musicLibrary capability only when the scenarios for your app require programmatic access and can't be realized by using the file picker. For an example of how to access files in a library, see Quickstart: Accessing files programmatically. |
| Pictures | The picturesLibrary capability provides programmatic access to the user's Pictures, allowing the app to enumerate and access all files in the library without user interaction. This capability is typically used in photo apps that make use of the entire Pictures library. The file picker provides a robust UI mechanism that lets users open files for use with an app. Declare the picturesLibrary capability only when the scenarios for your app require programmatic access and can't be realized them by using the file picker. For an example of how to access files in a library, see Quickstart: Accessing files programmatically. |
| Videos | The videosLibrary capability provides programmatic access to the user's Videos, allowing the app to enumerate and access all files in the library without user interaction. This capability is typically used in movie-playback apps that make use of the entire Videos library. The file picker provides a robust UI mechanism that lets users open files for use with an app. Declare the videosLibrary capability only when the scenarios for your app require programmatic access and can't be realized by using the file picker. For an example of how to access files in a library, see Quickstart: Accessing files programmatically. |
| Removable Storage | The removableStorage capability provides programmatic access to files on removable storage, like USB keys and external hard drives, filtered to the file-type associations declared in the package manifest. For example, if a document-reader app declares a .doc file-type association, it can open .doc files on the removable storage device, but not other types of files. Be careful when declaring this capability, because users may include a variety of info in their removable storage devices, and will expect your app to provide a valid justification for programmatic access to the removable storage for all files of the declared type. Users will expect your app to handle any file associations that you declare. So don't declare file associations that your app cannot handle responsibly. The file picker provides a robust UI mechanism that lets users open files for use with an app. Declare the removableStorage capability only when the scenarios for your app require programmatic access and can't be realized by using the file picker. |
| Internet and public networks | There are two capabilities that provide different levels of access to the Internet and public networks. These capabilities grant different access depending on if the app is running on Windows or Windows Phone. On Windows, the internetClient capability indicates that apps can receive incoming data from the Internet. Cannot act as a server. No local network access. On Windows, the internetClientServer capability indicates that apps can receive incoming data from the Internet. Can act as a server. No local network access. On Windows Phone, the internetClient capability indicates that apps have full local and Internet access and can act as a server. Inbound access to critical ports is always blocked. On Windows Phone, the internetClientServer capability indicates that apps have full local and Internet access and can act as a server. Inbound access to critical ports is always blocked. On Windows, most apps that have a web service component will use internetClient. Apps that enable peer-to-peer (P2P) scenarios where the app needs to listen for incoming network connections should use internetClientServer. The internetClientServer capability includes the access that the internetClient capability provides, so you don't need to specify internetClient when you specify internetClientServer. Note Windows Phone Store apps have a single network capability that enables all network access for the app. The internetClientServer capability enables complete access to the network for both client operations (outbound access) and server operations (inbound access). However, if any of the network capabilities (internetClient, internetClientServer, or privateNetworkClientServer) are specified in the Package.appxmanifest file, a Windows Phone Store app has complete access to the network at run time for both client and server operations. While you’re developing and testing your Windows Phone Store app app in Visual Studio, you get the networking capability (Internet (Client & Server)) when you run the app, even if you haven’t specified this capability in the app manifest file. When you publish your app, however, your app does not automatically get the networking capability. Make sure you check the Internet (Client & Server) capability on the Capabilities page of Manifest Designer if your app requires network connectivity. |
| Home and work networks | The privateNetworkClientServer capability provides inbound and outbound access to home and work networks through the firewall. This capability is typically used for games that communicate across the local area network (LAN), and for apps that share data across a variety of local devices. If your app specifies musicLibrary, picturesLibrary, or videosLibrary, you don't need to use this capability to access the corresponding library in a Home Group. On Windows, this capability does not provide access to the Internet. On Windows Phone, this capability provides the same access as internetClient or internetClientServer. |
| Appointments | The appointments capability provides access to the user’s appointment store. This capability allows read access to appointments obtained from the synced network accounts and to other apps that write to the appointment store. With this capability, your app can create new calendars and write appointments to calendars that it creates. |
| Contacts | The contacts capability provides access to the aggregated view of the contacts from various contacts stores. This capability gives the app limited access (network permitting rules apply) to contacts that were synced from various networks and the local contact store. |
| Code generation | The codeGeneration capability allows apps to generate code dynamically. |
| AllJoyn | The allJoyn capability allows AllJoyn-enabled apps and devices on a network to discover and interact with each other. All apps that access APIs in the Windows.Devices.AllJoyn namespace must use this capability.. |
| Phone calls | The phoneCall capability allows apps to access all of the phone lines on the device and perform the following functions.
|
| Recorded Calls Folder | The recordedCallsFolder device capability allows apps to access the recorded calls folder. |
| User Account Information | The userAccountInformation capability gives apps the ability to access the user's name and picture. This capability is required to access some APIs in the Windows.System.User namespace. |
| VOIP calling | The voipCall capability allows apps to access the VOIP calling APIs in the Windows.ApplicationModel.Calls namespace. |
| 3D Objects | The objects3d capability allows apps to have programmatic access to the 3D object files. This capability is typically used in 3D apps and games that need access to the entire 3D objects library. This capability is required to access the folder that contains the 3d objects using APIs in the Windows.Storage namespace. |
| Read Blocked Messages | The blockedChatMessages capability allows apps to read SMS and MMS messages that have been blocked by the Spam Filter app. This capability is required to access the blocked messages using APIs in the Windows.ApplicationModel.Chat namespace. |
| Chat Message Access | The chat capability allows apps to read and delete text messages. This capability also allows apps to store chat messages in the system datastore. This capability is required to use APIs in the Windows.ApplicationModel.Chat namespace. |
Device capabilities
Device capabilities allow your app to access peripheral and internal devices. Device capabilities are specified with the DeviceCapability element in your app package manifest. This element may require additional child elements and some device capabilities need to be added to the package manifest manually. For more info, see How to specify device capabilities in a package manifest and Schema reference for Windows 8 Windows Store apps or Schema reference for Windows 8.1 and Windows Phone 8.1.
| Capability scenario | Capability usage |
|---|---|
| Location | The location capability provides access to location functionality that is retrieved from dedicated hardware like a GPS sensor in the PC or is derived from available network info. Apps must handle the case where the user has disabled location services from the Settings charm. For an example of how to detect the user’s location, see Detecting geolocation. |
| Microphone | The microphone capability provides access to the microphone’s audio feed, which allows the app to record audio from connected microphones. Apps must handle the case where the user has disabled the microphone from the Settings charm. For an example of how to record audio, see How to record audio or video. |
| Proximity | The proximity capability enables multiple devices in close proximity to communicate with one another. This capability is typically used in casual multi-player games and in apps that exchange information. Devices attempt to use the communication technology that provides the best possible connection, including Bluetooth, Wi-Fi, and the Internet. This capability is used only to initiate communication between the devices. For an example of how to use proximity to connect apps, see Quickstart: Connecting apps using tapping or browsing. |
| Webcam | The webcam capability provides access to the video feed of a built-in camera or external webcam, which allows the app to capture photos and videos. On Windows, apps must handle the case where the user has disabled the camera from the Settings charm. For an example of how to record video, see How to record audio or video. The webcam capability only grants access to the video stream. In order to grant access to the audio stream as well, the microphone capability must be added. |
| USB | The usb device capability enables access to APIs in the Windows.Devices.Usb namespace. By using the namespace, you can write an app that talks to a custom USB device. "Custom" in this context means, a peripheral device for which Microsoft does not provide an in-box class driver. This device capability requires child elements. For more info, see Updating the app manifest package for a USB device.
Note The USB APIs are not supported on Windows Phone.
|
| Human interface device (HID) | The humaninterfacedevice device capability enables access to APIs in the Windows.Devices.HumanInterfaceDevice namespace. This namespace lets your app access devices that support the Human Interface Device (HID) protocol. This device capability requires child elements. For more info, see How to specify device capabilities for HID. |
| Bluetooth GATT | The bluetooth.genericAttributeProfile device capability enables access to APIs in the Windows.Devices.Bluetooth.GenericAttributeProfile namespace. This namespace lets your app access Bluetooth LE devices through a collection of primary services, included services, characteristics, and descriptors. For more info, see How to specify device capabilities for Bluetooth. |
| Bluetooth RFCOMM | The bluetooth.rfcomm device capability enables access to APIs in the Windows.Devices.Bluetooth.Rfcomm namespace. This namespace supports the Basic Rate/Extended Data Rate (BR/EDR) transport and also lets your app access a device that implements Serial Port Profile (SPP). This device capability requires child elements. For more info, see How to specify device capabilities for Bluetooth. |
| Point of Sevice (POS) | The pointOfService device capability enables access to APIs in the Windows.Devices.PointOfService namespace. This namespace lets your Windows Store app access Point of Service (POS) barcode scanners and magnetic stripe readers. The namespace provides a vendor-neutral interface for accessing POS devices from various manufacturers from a Windows Store app.
Note The Point of Service APIs are not supported on Windows Phone.
|
Special capabilities
Special capabilities are intended for very specific scenarios. Use of these capabilities is highly restricted and subject to additional Store on boarding policy and review. There are cases where such capabilities are necessary and appropriate, such as banking with two-factor authentication, where users provide a smart card with a digital certificate that confirms their identity. Other apps may be designed primarily for enterprise customers and may need access to corporate resources that cannot be accessed without the user’s domain credentials.
Apps that apply the special-use capabilities require a company account to submit them to the Store. For more information about company accounts for Windows, see Account types, locations, and fees.
| Capability scenario | Capability usage |
|---|---|
| Enterprise authentication | Windows domain credentials enable a user to log into remote resources using their credentials, and act as if a user provided their user name and password. The enterpriseAuthentication special capability is typically used in line-of-business apps that connect to servers within an enterprise. You don't need this capability for generic communication across the Internet. The enterpriseAuthentication special capability is intended to support common line-of-business apps. Don't declare it in apps that don't need to access corporate resources. The file picker provides a robust UI mechanism that enables users to open files on a network share for use with an app. Declare the enterpriseAuthentication special capability only when the scenarios for your app require programmatic access, and you cannot realize them by using the file picker. |
| Shared user certificates | The sharedUserCertificates special capability enables an app to access software and hardware certificates, such as certificates stored on a smart card. This capability is typically used for financial or enterprise apps that require a smart card for authentication. |
| Documents | The documentsLibrary special capability provides programmatic access to the user's Documents, filtered to the file type associations declared in the package manifest, to support offline access to OneDrive. For example, if a DOC reader app declared a .doc file type association, it can open .doc files in Documents, but not other types of files. Apps that declare the documentsLibrary special capability can't access Documents on Home Group computers. The file picker provides a robust UI mechanism that enables users to open files for use with an app. Declare the documentsLibrary special capability only when you cannot use the file picker. To use the documentsLibrary special capability, an app must:
Apps that use the documentsLibrary special capability for these two purposes may also optionally use the capability to open embedded content within another document. Only the above uses of the documentsLibrary special capability are accepted. You can't use the Documents library in a Windows Phone Store app.
|