Advanced Search

Log In | Not a Member?

Contact ADC

Overview

This header contains generic OBEX constants, structs, and C API used for all OBEX communication over any transport. For specific transport API, see that transport's C API. For example, if you wanted to know more about the Bluetooth OBEX implementation, see the documentation for OBEXBluetooth.h.

This file also contains API that will assist in the construction and deconstruction of OBEX headers to and from raw bytes, as well as the creation of vCards and vEvents.

For more information about accessing Bluetooth devices, see Working With Bluetooth Devices.

Functions

OBEXAddApplicationParameterHeader

Add an bytes representing a connection ID to a dictionary of OBEX headers.

OBEXAddAuthorizationChallengeHeader

Add an authorization challenge header to a dictionary of OBEXheaders.

OBEXAddAuthorizationResponseHeader

Add an authorization Response header to a dictionary of OBEXheaders.

OBEXAddBodyHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddByteSequenceHeader

Add an arbitrary byte sequence header to a dictionary of OBEXheaders.

OBEXAddConnectionIDHeader

Add an bytes representing a connection ID to a dictionary of OBEX headers.

OBEXAddCountHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddDescriptionHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddHTTPHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddLengthHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddNameHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddObjectClassHeader

Add an object class header to a dictionary of OBEXheaders.

OBEXAddTargetHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddTime4ByteHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddTimeISOHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddTypeHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXAddUserDefinedHeader

Add a user-defined custom header to a dictionary of OBEXheaders.

OBEXAddWhoHeader

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXCreateVCard

Creates a formatted vCard, ready to be sent over OBEX or whatever.

OBEXCreateVEvent

Creates a formatted vEvent, ready to be sent over OBEX or whatever. You probably will embed the output in a vCalendar event.

OBEXGetHeaders

Take a data blob and looks for OBEX headers.

OBEXHeadersToBytes

Converts a dictionary of headers to a data pointer, from which you can extract as bytes and pass to the OBEX command/response functions.

OBEXSessionAbort

Send an abort command to a remote OBEX server.

OBEXSessionAbortResponse

Send a response to a abort command to the remote client.

OBEXSessionConnect

Establishes an OBEX connection to the target device for the session. If a transport connection is not open yet, it will be opened if possible.

OBEXSessionConnectResponse

Send a response to a connect command to the remote client.

OBEXSessionDelete

Destroy an OBEX session. If connections are open, they will (eventually) be terminated for you.

OBEXSessionDisconnect

Send a disconnect command to a remote OBEX server.

OBEXSessionDisconnectResponse

Send a response to a disconnect command to the remote client.

OBEXSessionGet

Send a get command to a remote OBEX server.

OBEXSessionGetAvailableCommandPayloadLength

Gets space available for your data for a particular command you are trying to send.

OBEXSessionGetAvailableCommandResponsePayloadLength

Gets space available for your data for a particular command response you are trying to send.

OBEXSessionGetMaxPacketLength

Gets current max packet length.

OBEXSessionGetResponse

Send a response to a get command to the remote client.

OBEXSessionHasOpenOBEXConnection

Allows you to test the session for an open OBEX connection for a particular session.

OBEXSessionPut

Send a put command to a remote OBEX server.

OBEXSessionPutResponse

Send a response to a put command to the remote client.

OBEXSessionSetPath

Send a set path command to a remote OBEX server.

OBEXSessionSetPathResponse

Send a response to a set path command to the remote client.

OBEXSessionSetServerCallback

Add an bytes representing a connection ID to a dictionary of OBEX headers.

OBEXError OBEXAddApplicationParameterHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

Application parameter data - should be tag/length/value triplets.

inHeaderDataLength

Length of application parameter data.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Application Request/Response Parameter headers - OBEX Spec, 2.2.11: Byte Sequence

Add an authorization challenge header to a dictionary of OBEXheaders.

OBEXError OBEXAddAuthorizationChallengeHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

bytes you want to put in the authorization challenge header.

inHeaderDataLength

length of the bytes you want to put in authorization challenge header.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Authorization Challenge header - OBEX Spec, 2.2.13: Authorization Challenge.

Add an authorization Response header to a dictionary of OBEXheaders.

OBEXError OBEXAddAuthorizationResponseHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

bytes you want to put in the authorization Response header.

inHeaderDataLength

length of the bytes you want to put in authorization Response header.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Authorization Response header - OBEX Spec, 2.2.14: Authorization Response.

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddBodyHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    Boolean isEndOfBody, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

Body header data.

inHeaderDataLength

Length of Body header data.

isEndOfBody

Set this flag if you want an end of body header instead of a body header.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Body,EndOfBody headers - OBEX Spec, 2.2.9: Byte Sequence

Add an arbitrary byte sequence header to a dictionary of OBEXheaders.

OBEXError OBEXAddByteSequenceHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

bytes you want to put in the byte sequence header.

inHeaderDataLength

length of the bytes you want to put in the byte sequence header.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Byte Sequence header - OBEX Spec, 2.2.5: Byte sequence.

Add an bytes representing a connection ID to a dictionary of OBEX headers.

OBEXError OBEXAddConnectionIDHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

Connection ID data. Should be 4 bytes in length only.

inHeaderDataLength

Length of Connection ID data. This should ONLY be set to equal 4.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

ConnectionID headers - OBEX Spec, 2.2.10: Byte Sequence

*** IMPORTANT NOTE: In bluetooth 1.0, using this function will allow you to pass in any value. You should not pass more than 4 bytes ever. In later releases, if the length passed is not 4, a kOBEXBadArgumentError error will be returned. ***

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddCountHeader(
    uint32_t count, 
    CFMutableDictionaryRef dictRef );  

Parameters

count

Count value you want to add to the OBEX header dictionary.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Count header - OBEX Spec, 2.2.1: 4 byte unsigned integer

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddDescriptionHeader(
    CFStringRef description, 
    CFMutableDictionaryRef dictRef );  

Parameters

description

Description you want to add to the OBEX header dictionary.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Description header - OBEX Spec, 2.2.6: (2-byte) Null terminated unicode string.

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddHTTPHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

HTTP header data.

inHeaderDataLength

Length of HTTP header data.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

HTTP header - OBEX Spec, 2.2.8: Byte Sequence

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddLengthHeader(
    uint32_t length, 
    CFMutableDictionaryRef dictRef );  

Parameters

length

Value of Length header you want to add to the OBEX header dictionary.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Length header - OBEX Spec, 2.2.4: 4 byte unsigned integer

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddNameHeader(
    CFStringRef name, 
    CFMutableDictionaryRef dictRef );  

Parameters

name

name you want to add to the OBEX header dictionary.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Name header - OBEX Spec, 2.2.2: (2-byte) Null terminated unicode string.

Add an object class header to a dictionary of OBEXheaders.

OBEXError OBEXAddObjectClassHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

bytes you want to put in the object class header.

inHeaderDataLength

length of the bytes you want to put in the object class header.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Object Class header - OBEX Spec, 2.2.15: Byte sequence.

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddTargetHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

Target header data.

inHeaderDataLength

Length of Target header data.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Target header - OBEX Spec, 2.2.7: Byte Sequence

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddTime4ByteHeader(
    uint32_t time4Byte, 
    CFMutableDictionaryRef dictRef );  

Parameters

time4Byte

4-byte time value you want to add to the OBEX header dictionary.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Time4Byte headers - OBEX Spec, 2.2.5: 4 Bytes

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddTimeISOHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

Target header data.

inHeaderDataLength

Length of Target header data.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

TimeISO header - OBEX Spec, 2.2.5: Byte Sequence

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddTypeHeader(
    CFStringRef type, 
    CFMutableDictionaryRef dictRef );  

Parameters

description

Description containing the name you want to add to the OBEX header dictionary.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Type header - OBEX Spec, 2.2.3: 1-byte Null terminated ascii string.

Add a user-defined custom header to a dictionary of OBEXheaders.

OBEXError OBEXAddUserDefinedHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

bytes you want to put in the user-defined header.

inHeaderDataLength

length of the bytes you want to put in user-defined header.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

User Defined header - OBEX Spec, 2.2.20: User Defined Headers.

Add a CFStringRef to a dictionary of OBEXheaders.

OBEXError OBEXAddWhoHeader(
    const void *inHeaderData, 
    uint32_t inHeaderDataLength, 
    CFMutableDictionaryRef dictRef );  

Parameters

inHeaderData

Who header data.

inHeaderDataLength

Length of Who header data.

dictRef

dictionary you have allocated to hold the headers. Make sure it's mutable.

Return Value

Error code, kOBEXSuccess (0) if success.

Discussion

Who headers - OBEX Spec, 2.2.10: Byte Sequence

Creates a formatted vCard, ready to be sent over OBEX or whatever.

CFDataRef OBEXCreateVCard(
    const void *inFirstName, 
    uint32_t inFirstNameLength, 
    const void *inLastName, 
    uint32_t inLastNameLength, 
    const void *inFriendlyName, 
    uint32_t inFriendlyNameLength, 
    const void *inNameCharset, 
    uint32_t inNameCharsetLength, 
    const void *inHomePhone, 
    uint32_t inHomePhoneLength, 
    const void *inWorkPhone, 
    uint32_t inWorkPhoneLength, 
    const void *inCellPhone, 
    uint32_t inCellPhoneLength, 
    const void *inFaxPhone, 
    uint32_t inFaxPhoneLength, 
    const void *inEMailAddress, 
    uint32_t inEMailAddressLength, 
    const void *inEMailAddressCharset, 
    uint32_t inEMailAddressCharsetLength, 
    const void *inOrganization, 
    uint32_t inOrganizationLength, 
    const void *inOrganizationCharset, 
    uint32_t inOrganizationCharsetLength, 
    const void *inTitle, 
    uint32_t inTitleLength, 
    const void *inTitleCharset, 
    uint32_t inTitleCharsetLength );  

Parameters

inNameCharset

A pointer to the charset data used for the name. Pass in a #defined charset for ease of use.

inNameCharsetLength

Length of name charset assed in above.

inFirstName

Pointer to data with Person's first name.

inFirstNameLength

Length of Person's first name passed in above.

inLastName

Pointer to data with Person's last name.

inLastNameLength

Length of Person's last name passed in above.

inFriendlyName

Pointer to data with Person's Friendly name.

inFriendlyNameLength

Length of Person's Friendly name passed in above.

inHomePhone

Pointer to data with Person's Home phone number.

inHomePhoneLength

Length of Person's Home phone number passed in above.

inWorkPhone

Work phone number.

inWorkPhoneLength

Length of Person's Work phone number passed in above.

inCellPhone

Cell phone number.

inCellPhoneLength

Length of Person's Cell phone number passed in above.

inFaxPhone

Fax phone number.

inFaxPhoneLength

Length of Person's Fax phone number passed in above.

inEMailAddress

EMailAddress of person.

inEMailAddressLength

Length of Person's EMailAddress passed in above.

inEMailAddressCharset

Charset of EMailAddress of person.

inEMailAddressCharsetLength

Length of Person's EMailAddress charset passed in above.

inOrganization

Pointer to Organization/business data.

inOrganizationLength

Length of Organization/business data.

inOrganizationCharset

Pointer to the charset the Organization/business is in.

inOrganizationCharsetLength

Length of data for the Organization/business charset.

inTitle

Pointer to data with Title of person in biz/org.

inTitleLength

Length of Title of person in biz/org.

inOrganizationCharset

Pointer to the charset the Title is in.

inOrganizationCharsetLength

Length of data for the Title charset.

Return Value

An CFDataRef containing the compiled data. nil if we failed.

Discussion

All parameters are optional. The CFDataRef returned to you is NOT retained. Retain it if you want to keep it.

Creates a formatted vEvent, ready to be sent over OBEX or whatever. You probably will embed the output in a vCalendar event.

CFDataRef OBEXCreateVEvent(
    const char *inCharset, 
    uint32_t inCharsetLength, 
    const char *inEncoding, 
    uint32_t inEncodingLength, 
    const char *inEventStartDate, 
    uint32_t inEventStartDateLength, 
    const char *inEventEndDate, 
    uint32_t inEventEndDateLength, 
    const char *inAlarmDate, 
    uint32_t inAlarmDateLength, 
    const char *inCategory, 
    uint32_t inCategoryLength, 
    const char *inSummary, 
    uint32_t inSummaryLength, 
    const char *inLocation, 
    uint32_t inLocationLength, 
    const char *inXIRMCLUID, 
    uint32_t inXIRMCLUIDLength );  

Parameters

inCharset

The Charset the passed data is in. Pass in a #defined charset for ease of use.

inCharsetLength

The length of the Charset passed data.

inEncoding

The encoding of the summary and location fields.

inCharsetLength

The length of the Charset passed data.

inEventStartDate

Start of event date, in the (ISO8601) format: YYYYMMDDTHHMMSS. e.g. 19960415T083000 = 8:30 am on April 15, 1996. All time values should be in LOCAL time.

inCharsetLength

The length of the Charset passed data.

inEventEndDate

End of event date.

inCharsetLength

The length of the Charset passed data.

inAlarmDate

Date of Alarm for event, in the format: YYYYMMDDTHHMMSS.

inCharsetLength

The length of the Charset passed data.

inCategory

Category of event, such as "MEETING" or "PHONE CALL".

inCharsetLength

The length of the Charset passed data.

inSummary

Summary of event. Max length is 36 bytes. Longer will result in a bad argument error.

inCharsetLength

The length of the Charset passed data.

inLocation

Summary of event. Max length is 20 bytes. Longer will result in a bad argument error.

inCharsetLength

The length of the Charset passed data.

inXIRMCLUID

The IRMC Local Unique Identifier Label, max length 12 bytes. Longer will result in a bad argument error.

inCharsetLength

The length of the Charset passed data.

Return Value

A valid CFDataRef - nil if we failed.

Discussion

All parameters are optional. The CFDataRef returned to you is NOT retained. Retain it if you want to keep it. Be aware that certain devices such as Ericsson phones MUST have certain fields, such as a start and end date.

Take a data blob and looks for OBEX headers.

CFDictionaryRef OBEXGetHeaders(
    const void *inData,
    size_t inDataSize );  

Parameters

inData

The data chunk with the headers you are interested in.

inDataSize

The size of the buffer you are passing in.

Return Value

A CFDictionary with the headers found in the data blob inside it.

Discussion

You should use this when your callback for PUTs, GETs, etc. give you a data chunk and a size. Pass these params to this function and you will receive a dictionary back full of the parse headers. You can use the CFDictionary calls to get objects out of it, based on the header keys defined above. You are responsible for releasing the CFDictionary returned to you. Example usage:

	CFDictionaryRef   dictionary = OBEXGetHeaders( data, dataLength );
	if( dictionary )
	{
		if( CFDictionaryGetCountOfKey( dictionary, kOBEXHeaderIDKeyName ) > 0 )
		{			
			CFStringRef theStringRef;
			
			theStringRef = (CFStringRef) CFDictionaryGetValue( dictionary, kOBEXHeaderIDKeyName );
			if( theStringRef )
			{				
				// Display it, use it as a filename, whatever.
			}
		}
		
		if( CFDictionaryGetCountOfKey( dictionary, kOBEXHeaderIDKeyConnectionID ) > 0 )
		{
			CFDataRef theDataRef;
			
			theDataRef = (CFDataRef) CFDictionaryGetValue( dictionary, kOBEXHeaderIDKeyConnectionID );
			if( theDataRef )
			{
				// now we have data representing the connection ID.
			}
		}
		
		CFRelease( dictionary );
	}

Converts a dictionary of headers to a data pointer, from which you can extract as bytes and pass to the OBEX command/response functions.

CFMutableDataRef OBEXHeadersToBytes(
    CFDictionaryRef dictionaryOfHeaders );  

Parameters

dictionaryOfHeaders

dictionary that you have added headers to with the above OBEXAddXXXHeader functions.

Return Value

Mutable data ref containing the bytes of all headers.

Discussion

Returns a CFMutableDataRef containing all the header data found in the dictionary, formatted according to the OBEX/IrMC spec. YOU MUST RELEASE IT when you are finished with it (ie. when the OBEX request is complete). All OBEX-specification defined headers are supported and should be returned to the dictionary. Use the keys defined above to get headers from dictionary. Example usage:

	Example usage:

	CFMutableDictionaryRef	dictionary;
	CFMutableDataRef		mGetHeadersDataRef;
	uint8_t* 				headerDataPtr;
	uint32_t 				headerDataLength;
	
	dictionary = CFDictionaryCreateMutable( kCFAllocatorDefault, 0, &kCFCopyStringDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks );
	
	// Package up desired headers.

	OBEXAddTypeHeader( CFSTR( "text/x-vCard" ), dictionary ); 

	mGetHeadersDataRef = OBEXHeadersToBytes( dictionary );

	headerDataPtr = CFDataGetBytePtr( mGetHeadersDataRef );
	headerDataLength = CFDataGetLength( mGetHeadersDataRef );
	
	// From here I can pass it to any OBEX command, such as OBEXPut...

Send an abort command to a remote OBEX server.

OBEXError OBEXSessionAbort(
    OBEXSessionRef inSessionRef, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefcon );  

Parameters

inSessionRef

A valid session reference.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Send a response to a abort command to the remote client.

OBEXError OBEXSessionAbortResponse(
    OBEXSessionRef inSessionRef, 
    OBEXOpCode inResponseOpCode, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inResponseOpCode

What response code you want to send to the remote client.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Establishes an OBEX connection to the target device for the session. If a transport connection is not open yet, it will be opened if possible.

OBEXError OBEXSessionConnect(
    OBEXSessionRef inSessionRef, 
    OBEXFlags inFlags, 
    OBEXMaxPacketLength inMaxPacketLength, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inFlags

Flags, as defined in the OBEX spec for this command.

inMaxPacketLength

Maximum packet length you wish to allow. May be negiotiated with host to be less or more than you specify.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback parameter will result in an error. If you have already established an OBEX connection and you call this again you will get an 'kOBEXSessionAlreadyConnectedError' as a result.

Send a response to a connect command to the remote client.

OBEXError OBEXSessionConnectResponse(
    OBEXSessionRef inSessionRef, 
    OBEXOpCode inResponseOpCode, 
    OBEXFlags inFlags, 
    OBEXMaxPacketLength inMaxPacketLength, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inResponseOpCode

What response code you want to send to the remote client.

inFlags

Flags, as defined in the OBEX spec for this command.

inConstants

Constants, as defined in the OBEX spec for this command.

inMaxPacketLength

Max packet length you want to support. Must be smaller or equal to the max packet length specified by the remote client.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Destroy an OBEX session. If connections are open, they will (eventually) be terminated for you.

OBEXError OBEXSessionDelete(
    OBEXSessionRef inSessionRef );  

Parameters

inSessionRef

A valid service reference.

Return Value

An error code value. 0 if successful.

Send a disconnect command to a remote OBEX server.

OBEXError OBEXSessionDisconnect(
    OBEXSessionRef inSessionRef, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Send a response to a disconnect command to the remote client.

OBEXError OBEXSessionDisconnectResponse(
    OBEXSessionRef inSessionRef, 
    OBEXOpCode inResponseOpCode, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inResponseOpCode

What response code you want to send to the remote client.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Send a get command to a remote OBEX server.

OBEXError OBEXSessionGet(
    OBEXSessionRef inSessionRef, 
    Boolean inIsFinalChunk, 
    void *inHeadersData, 
    size_t inHeadersDataLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inIsFinalChunk

TRUE or FALSE - is this the last chunk of header data for this GET.

inHeadersData

Headers containing data to GET.

inHeadersDataLength

Size of header data.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Gets space available for your data for a particular command you are trying to send.

OBEXError OBEXSessionGetAvailableCommandPayloadLength(
    OBEXSessionRef inSessionRef,
    OBEXOpCode inOpCode,
    OBEXMaxPacketLength *outLength );  

Parameters

inSessionRef

A valid session reference.

inOpCode

An opcode of what command you are trying to send.

outLength

Space available for your header data in the payload area for a particular command.

Return Value

An error code value. 0 if successful.

Discussion

The OBEXSession takes care of packaging OBEX opcodes and other information into the proper packet format, allowing you to focus on sending the proper OBEX headers in your commands and command responses. This formatting and datas requires a small bit of information that varies depending on what command or response you are sending. Thus, you should call this function to find out how much space will be left for your headers before you send the command, allowing you to properly chop up your headers before sending them. This will guarantee that (a) you use up all the available space in a packet and (b) that you do not get an error trying to send too much information at once.

Gets space available for your data for a particular command response you are trying to send.

OBEXError OBEXSessionGetAvailableCommandResponsePayloadLength(
    OBEXSessionRef inSessionRef,
    OBEXOpCode inOpCode,
    OBEXMaxPacketLength *outLength );  

Parameters

inSessionRef

A valid session reference.

inOpCode

A command opcode that you are responding to. For example, if you receiving a Put command, and want to send back a "bad request" response, you should still pass in the Put command opcode for that response.

outLength

Space available for your header data in the payload area for a particular command.

Return Value

An error code value. 0 if successful.

Discussion

The OBEXSession takes care of packaging OBEX opcodes and other information into the proper packet format, allowing you to focus on sending the proper OBEX headers in your commands and command responses. This formatting and datas requires a small bit of information that varies depending on what command or response you are sending. Thus, you should call this function to find out how much space will be left for your headers before you send the command, allowing you to properly chop up your headers before sending them. This will guarantee that (a) you use up all the available space in a packet and (b) that you do not get an error trying to send too much information at once.

Gets current max packet length.

OBEXError OBEXSessionGetMaxPacketLength(
    OBEXSessionRef inSessionRef,
    OBEXMaxPacketLength *outLength );  

Parameters

inSessionRef

A valid session reference.

outLength

Max packet length.

Return Value

An error code value. 0 if successful.

Discussion

This value *could* change before and after a connect command has been sent or a connect command response has been received, since the recipient could negotiate a lower max packet size.

Send a response to a get command to the remote client.

OBEXError OBEXSessionGetResponse(
    OBEXSessionRef inSessionRef, 
    OBEXOpCode inResponseOpCode, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inResponseOpCode

What response code you want to send to the remote client.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Allows you to test the session for an open OBEX connection for a particular session.

OBEXError OBEXSessionHasOpenOBEXConnection(
    OBEXSessionRef inSessionRef, 
    Boolean *outIsConnected );  

Parameters

inSessionRef

A valid session reference.

outIsConnected

A valid ptr to an OBEXSessionRef; will contain the newly created session if return value is kOBEXSuccess.

Return Value

An error code value. 0 if successful.

Discussion

This method will return true only if (a) you are transport-connected to another OBEX target and (b) an OBEX Connect command has been issued and received successfully.

Send a put command to a remote OBEX server.

OBEXError OBEXSessionPut(
    OBEXSessionRef inSessionRef, 
    Boolean inIsFinalChunk, 
    void *inHeadersData, 
    size_t inHeadersDataLength, 
    void *inBodyData, 
    size_t inBodyDataLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inIsFinalChunk

TRUE or FALSE - is this the last chunk of header data for this PUT.

inHeadersData

Headers containing data to PUT. Don't include your body header data here.

inHeadersDataLength

Size of header data. Don't include your body header data here.

inBodyData

Data for the BODY header to PUT. DO NOT package your data in an actual BODY header, this will be done for you, based on the finalChunk flag you pass in above (since based on this flag the header ID will be either a BODY or ENDOFBODY header).

inBodyDataLength

Size of Data for the BODY header to PUT.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Send a response to a put command to the remote client.

OBEXError OBEXSessionPutResponse(
    OBEXSessionRef inSessionRef, 
    OBEXOpCode inResponseOpCode, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inResponseOpCode

What response code you want to send to the remote client.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Send a set path command to a remote OBEX server.

OBEXError OBEXSessionSetPath(
    OBEXSessionRef inSessionRef, 
    OBEXFlags inFlags, 
    OBEXConstants inConstants, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefcon );  

Parameters

inSessionRef

A valid session reference.

inFlags

Flags, as defined in the OBEX spec for this command.

inConstants

Constants, as defined in the OBEX spec for this command.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

Send a response to a set path command to the remote client.

OBEXError OBEXSessionSetPathResponse(
    OBEXSessionRef inSessionRef, 
    OBEXOpCode inResponseOpCode, 
    void *inOptionalHeaders, 
    size_t inOptionalHeadersLength, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inResponseOpCode

What response code you want to send to the remote client.

inOptionalHeaders

Ptr to optional headers you can supply to the command. DO NOT dispose of this pointer until you callback is called with a success.

inOptionalHeadersLength

Size of data at the specified ptr.

inCallback

A valid callback. Will be called for progress, errors and completion.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

As all commands for OBEX sessions, this command is asynchronous only. A NULL callback paramter will result in an error.

OBEXError OBEXSessionSetServerCallback(
    OBEXSessionRef inSessionRef, 
    OBEXSessionEventCallback inCallback, 
    void *inUserRefCon );  

Parameters

inSessionRef

A valid session reference.

inCallback

A valid callback. Will be called for progress, errors and completion by server sessions only.

inUserRefCon

Optional parameter; can contain anything you wish. Will be returned in your callback just as you passed it.

Return Value

An error code value. 0 if successful.

Discussion

Sets callback to be used when an event occurs on an OBEXSession. This is important for OBEX servers, as you will need a way to be called back when the first command is sent to you. So, be sure to set yourself up to listen for events when you are ready to receive them.

Typedefs

OBEXAbortCommandData

typedef struct OBEXAbortCommandData OBEXAbortCommandData;  

Discussion

Part of the OBEXSessionEvent structure. Is readable when the event is of type kOBEXSessionEventTypeAbortCommandReceived (see OBEXSessionEventTypes).

OBEXAbortCommandResponseData

typedef struct OBEXAbortCommandResponseData OBEXAbortCommandResponseData;  

Discussion

Part of the OBEXSessionEvent structure. Is readable when the event is of type kOBEXSessionEventTypeAbortCommandResponseReceived (see OBEXSessionEventTypes).

OBEXConnectCommandData

typedef struct OBEXConnectCommandData OBEXConnectCommandData;  

Discussion

Part of the OBEXSessionEvent structure. Is readable when the event is of type kOBEXSessionEventTypeConnectCommandReceived (see OBEXSessionEventTypes).

OBEXConnectCommandResponseData

typedef struct OBEXConnectCommandResponseData OBEXConnectCommandResponseData;  

Discussion

Part of the OBEXSessionEvent structure. Is readable when the event is of type kOBEXSessionEventTypeConnectCommandResponseReceived (see OBEXSessionEventTypes).

OBEXDisconnectCommandData

typedef struct OBEXDisconnectCommandData OBEXDisconnectCommandData;  

Discussion

Part of the OBEXSessionEvent structure. Is readable when the event is of type kOBEXSessionEventTypeDisconnectCommandReceived (see OBEXSessionEventTypes).

OBEXDisconnectCommandResponseData

typedef struct OBEXDisconnectCommandResponseData OBEXDisconnectCommandResponseData;  

Discussion

Part of the OBEXSessionEvent structure. Is readable when the event is of type kOBEXSessionEventTypeDisconnectCommandResponseReceived (see OBEXSessionEventTypes).

Codes for OBEX errors. If the return value was not in the following range, then it is most likely resulting from kernel code/IOKit, and you should consult IOReturn.h for those codes.

OBEXErrorCodes

typedef int32_t OBEXError;  

OBEXErrorData

typedef struct