Evaluating Capabilities Programmatically

For ASP.NET mobile controls, the same functionality provided through the <deviceFilters> section of Web.config can be accessed programmatically using the HasCapability method of the MobileCapabilities class. By calling this method, you can evaluate comparison methods.

The HasCapability method is useful for programmatically determining whether the current device satisfies a device filter declared in Web.config. The MobileCapabilities instance caches the evaluation of the HasCapability method so that subsequent requests for the same capability name and optional argument do not need to be reevaluated. The HasCapability method is useful when you want to write code that matches how the ASP.NET page framework selects among various choices in a <DeviceSpecific> element.

Note   The HasCapability method does not support <DeviceSpecific> element choices that call methods defined on the page.

The HasCapability method has two arguments, capabilityName, which is the name of the device evaluation method, property, or item in the capability dictionary, and optionalArgument, which is any argument that the capabilityName argument requires. The HasCapability method performs its evaluation in the following order:

  1. Checks whether capabilityName is the name of a device filter specified in Web.config.

    Note   The HasCapability method evaluates the <DeviceSpecific>/<Choice> construct by setting optionalArgument argument to null.

  2. If the test in step 1 returns true and the filter is a delegated evaluator, which is a filter that uses a custom method to evaluate the specified data, the HasCapability method invokes the delegate with the argument provided in the optionalArgument parameter and returns the result.

  3. If the test in step 1 is true and the filter is a comparison evaluator, which is a filter that compares a capability name to a value, the HasCapability method calls itself with the capability name and argument provided in the evaluator (any original optionalArgument parameter is ignored) and returns the result.

  4. If the MobileCapabilities object has a property named capabilityName, the HasCapability method casts this property to a string and returns true if the optionalArgument is equal to this string. Boolean comparisons are not case-sensitive; other comparisons are case-sensitive. Therefore, true is equivalent to True, but left is not equivalent to Left.

  5. If no property exists, the HasCapability method looks up capabilityName in the capabilities dictionary associated with the MobileCapabilities object. If capabilityName exists, the HasCapability method compares it to the optionalArgument parameter and returns the result. Because the dictionary maintains strings, no casting is required.

  6. If these tests fail, the HasCapability method throws an ArgumentOutOfRange exception.

Examples

The following examples show how you might call the HasCapability method, where GPSEnabled and ScreenBitDepth are defined filters, properties, or values in the Items collection.

[C#]

((MobileCapabilities)Request.Browser).HasCapability("GPSEnabled", null);

or

((MobileCapabilities)Request.Browser).HasCapability("ScreenBitDepth", "8");

See Also

Device Capabilities Table | Device Evaluation Methods | Device Filtering Recommendations | Device-Specific Rendering | <filter> Element