IOBluetoothSDPDataElement

Overview

An instance of this class represents a single SDP data element as defined by the Bluetooth SDP spec.

Discussion

The data types described by the spec have been mapped onto the base Foundation classes NSNumber, NSArray, NSData as well as IOBluetoothSDPUUID. The number and boolean types (type descriptor 1, 2 and 5) are represented as NSNumber objects with the exception of 128-bit numbers which are represented as NSData objects in their raw format. The UUID type (type descriptor 3) is represented by IOBluetoothSDPUUID. The string and URL types (type descriptor 4 and 8) are represented by NSString. The sequence types (type descriptor 6 and 7) are represented by NSArray.

Typically, you will not need to create an IOBluetoothSDPDataElement directly, the system will do that automatically for both client and server operations. However, the current API for adding SDP services to the system does allow the use of an NSDictionary based format for creating new services. The purpose for that is to allow a service to be built up completely in a text file (a plist for example) and then easily imported into an app and added to the system without a lot of tedious code to build up the entire SDP service record.

The basis for that NSDictionary structure comes from the IOBluetoothSDPDataElement. At its simplest, a data element is made up of three parts: the type descriptor, the size (from which the size descriptor is generated) and the actual value. To provide a complete representation of a data element, an NSDictionary with three entries can be used. Each of the three entries has a key/value pair representing one of the three attributes of a data element. The first key/value pair has a key 'DataElementType' that contains a number value with the actual type descriptor for the data element. The second pair has a key 'DataElementSize' that contains the actual size of the element in bytes. The size descriptor will be calculated based on the size and type of the element. The third pair is the value itself whose key is 'DataElementValue' and whose type corresponds to the type mapping above.

In addition to this complete description of a data element, their are some shortcuts that can be used for some of the common types and sizes.

If the 'DataElementType' value is one of the numeric types (1, 2), the 'DataElementValue' can be an NSData instead of an NSNumber. In that case, the numeric data is taken in network byte order (MSB first). Additionally, the 'DataElementSize' parameter may be omitted and the size will be taken from the length of the data object.

If the 'DataElementType' value is the nil type (0), no 'DataElementSize' or 'DataElementValue' entries are needed.

If the 'DataElementType' value is any of the other types, the 'DataElementSize' entry is not needed since the size will be taken directly from the value (data, array, string).

In the case where the element is an unsigned, 32-bit integer (type descriptor 1, size descriptor 2), the value itself may simply be a number (instead of a dictionary as in the previous examples).

In the case where the element is a UUID (type descriptor 3), the value itself may be a data object. The UUID type will be inferred and the size taken from the length of the data object.

In the case where the element is a text string (type descriptor 4), the value may be a string object. The text string type will be inferred and the size taken from the length of the string.

In the case where the element is a data element sequence, the value may be an array object. The type will be inferred and the size taken from the length of the array. Additionally, the array must contain sub-elements that will be parsed out individually.

Methods

-containsDataElement:

Checks to see if the target data element is the same as the dataElement parameter or if it contains the dataElement parameter (if its a sequence type).

-containsValue:

Checks to see if the target data element's value is the same as the value parameter or if it contains the value parameter.

-getArrayValue

If the data element is represented by an array object, it returns the value as an NSArray.

-getDataValue

If the data element is represented by a data object, it returns the value as an NSData.

-getNumberValue

If the data element is represented by a number, it returns the value as an NSNumber.

-getSDPDataElementRef

Returns an IOBluetoothSDPDataElementRef representation of the target IOBluetoothSDPDataElement object.

-getSize

Returns the size in bytes of the target data element.

-getSizeDescriptor

Returns the SDP spec defined data element size descriptor for the target data element.

-getStringValue

If the data element is represented by a string object, it returns the value as an NSString.

-getTypeDescriptor

Returns the SDP spec defined data element type descriptor for the target data element.

-getUUIDValue

If the data element is a UUID (type 3), it returns the value as an IOBluetoothSDPUUID.

-getValue

Returns the object value of the data element.

-initWithElementValue:

Initializes a new IOBluetoothSDPDataElement with the given value.

-initWithType:sizeDescriptor:size:value:

Initializes a new IOBluetoothSDPDataElement with the given attributes.

-isEqual:

Compares the target data element with the given object.

+withElementValue:

Creates a new IOBluetoothSDPDataElement with the given value.

+withSDPDataElementRef:

Method call to convert an IOBluetoothSDPDataElementRef into an IOBluetoothSDPDataElement *.

+withType:sizeDescriptor:size:value:

Creates a new IOBluetoothSDPDataElement with the given attributes.

Checks to see if the target data element is the same as the dataElement parameter or if it contains the dataElement parameter (if its a sequence type).

- (BOOL)containsDataElement:(IOBluetoothSDPDataElement *)dataElement; 

Parameters

dataElement

The data element to compare with (and search for).

Return Value

Returns TRUE if the target either matches the given data element or if it contains the given data element.

Discussion

If the target data element is not a sequence type, this method simply compares the two data elements. If it is a sequence type, it will search through the sequence (and sub-sequences) for the dataElement parameter.

Checks to see if the target data element's value is the same as the value parameter or if it contains the value parameter.

- (BOOL)containsValue:(NSObject *)cmpValue; 

Parameters

cmpValue

The value to compare with (and search for).

Return Value

Returns TRUE if the target's value either matches the given value or if it contains the given value.

Discussion

This method works just like -containsDataElement: except that it is comparing the value objects directly.

If the data element is represented by an array object, it returns the value as an NSArray.

- (NSArray *)getArrayValue; 

Return Value

Returns an NSArray representation of the data element if it is a sequence type.

Discussion

The data types represented by an array object are 6 (data element sequence) and 7 (data element alternative).

If the data element is represented by a data object, it returns the value as an NSData.

- (NSData *)getDataValue; 

Return Value

Returns an NSData representation of the data element if it is a 128-bit number.

Discussion

The data types represented by a data object are 128-bit versions of 1 (unsigned int) and 2 (signed int).

If the data element is represented by a number, it returns the value as an NSNumber.

- (NSNumber *)getNumberValue; 

Return Value

Returns an NSNumber representation of the data element if it is a numeric type.

Discussion

The data types represented by a number are 1 (unsigned int), 2 (signed int) and 5 (boolean) except for 128-bit versions of 1 and 2.

Returns an IOBluetoothSDPDataElementRef representation of the target IOBluetoothSDPDataElement object.

- (IOBluetoothSDPDataElementRef)getSDPDataElementRef; 

Return Value

Returns an IOBluetoothSDPDataElementRef representation of the target IOBluetoothSDPDataElement object.

Returns the size in bytes of the target data element.

- (UInt32)getSize; 

Return Value

Returns the size in bytes of the target data element.

Discussion

The size is valid whether the data element has a fixed or variable size descriptor.

Returns the SDP spec defined data element size descriptor for the target data element.

- (BluetoothSDPDataElementSizeDescriptor)getSizeDescriptor; 

Return Value

Returns the size descriptor for the target data element.

If the data element is represented by a string object, it returns the value as an NSString.

- (NSString *)getStringValue; 

Return Value

Returns an NSString representation of the data element if it is a text or URL type.

Discussion

The data types represented by a string object are 4 (text string) and 8 (URL).

Returns the SDP spec defined data element type descriptor for the target data element.

- (BluetoothSDPDataElementTypeDescriptor)getTypeDescriptor; 

Return Value

Returns the type descriptor for the target data element.

If the data element is a UUID (type 3), it returns the value as an IOBluetoothSDPUUID.

- (IOBluetoothSDPUUID *)getUUIDValue; 

Return Value

Returns an IOBluetoothSDPUUID representation of the data element if it is a UUID.

Returns the object value of the data element.

- (NSObject *)getValue; 

Return Value

Returns the object value of the target data element.

Discussion

The value returned may be an NSNumber, NSString, NSData, NSArray or IOBluetoothSDPDataElement depending on the type of the data element.

Initializes a new IOBluetoothSDPDataElement with the given value.

- (id)initWithElementValue:(NSObject *)element; 

Parameters

element

The data element value of one of the specified types.

Return Value

Returns self if successful. Returns nil if there was an error parsing the element value.

Discussion

The value must follow the format listed above and must be an instance of NSData, NSString, NSNumber, NSArray, NSDictionary, IOBluetoothSDPUUID.

Initializes a new IOBluetoothSDPDataElement with the given attributes.

- (id)initWithType:(BluetoothSDPDataElementTypeDescriptor)newType 
        sizeDescriptor:(BluetoothSDPDataElementSizeDescriptor)newSizeDescriptor 
        size:(UInt32)newSize value:(NSObject *)newValue; 

Parameters

newType

The type descriptor for the data element.

newSizeDescriptor

The size descriptor for the data element (verify it matches the size parameter).

newSize

The size of the data element in bytes (make sure it is a valid size for the given size descriptor).

newValue

The raw value itself. This must be the base NSString, NSNumber, NSArray or NSData objects. It may not be NSDictionary. If a dictionary format is present, use +withElementValue:.

Return Value

Returns self if successful. Returns nil if an error is encountered (not likely due to the limited error checking currently done).

Discussion

Warning - be careful using this method. There is next to no error checking done on the attributes. It is entirely possible to construct an invalid data element. It is recommended that +withElementValue: be used instead of this one.

Compares the target data element with the given object.

- (BOOL)isEqual:(id)cmpObject; 

Parameters

cmpObject

The object to compare with.

Return Value

Returns TRUE if the target data element is the same as the given object or if it's value matches the given object.

Discussion

This method will compare a data element with either another data element or a data element value.

Creates a new IOBluetoothSDPDataElement with the given value.

+ (IOBluetoothSDPDataElement *)withElementValue:(NSObject *)element; 

Parameters

element

The data element value of one of the specified types.

Return Value

Returns the newly allocated data element object. Returns nil if there was an error parsing the element value. The returned IOBluetoothSDPDataElement object has been autoreleased, so it is not necessary for the caller to release it. If the object is to be referenced and kept around, retain should be called.

Discussion

The value must follow the format listed above and must be an instance of NSData, NSString, NSNumber, NSArray, NSDictionary, IOBluetoothSDPUUID.

Method call to convert an IOBluetoothSDPDataElementRef into an IOBluetoothSDPDataElement *.

+ (IOBluetoothSDPDataElement *)withSDPDataElementRef:(IOBluetoothSDPDataElementRef)sdpDataElementRef; 

Parameters

sdpDataElementRef

IOBluetoothSDPDataElementRef for which an IOBluetoothSDPDataElement * is desired.

Return Value

Returns the IOBluetoothSDPDataElement * for the given IOBluetoothSDPDataElementRef.

Creates a new IOBluetoothSDPDataElement with the given attributes.

+ (IOBluetoothSDPDataElement *)withType:(BluetoothSDPDataElementTypeDescriptor)type 
        sizeDescriptor:(BluetoothSDPDataElementSizeDescriptor)newSizeDescriptor 
        size:(UInt32)newSize value:(NSObject *)newValue; 

Parameters

type

The type descriptor for the data element.

newSizeDescriptor

The size descriptor for the data element (verify it matches the size parameter).

newSize

The size of the data element in bytes (make sure it is a valid size for the given size descriptor).

newValue

The raw value itself. This must be the base NSString, NSNumber, NSArray or NSData objects. It may not be NSDictionary. If a dictionary format is present, use +withElementValue:.

Return Value

Returns the newly allocated data element object. Returns nil if an error is encountered (not likely due to the limited error checking currently done). The returned IOBluetoothSDPDataElement object has been autoreleased, so it is not necessary for the caller to release it. If the object is to be referenced and kept around, retain should be called.

Discussion

Warning - be careful using this method. There is next to no error checking done on the attributes. It is entirely possible to construct an invalid data element. It is recommended that +withElementValue: be used instead of this one.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.