ADC Home > Reference Library > Reference > Core Foundation > Internet & Web >

Hide TOC

Web Services Core Framework Functions

Functions by Task

Method Invocation Functions

The method invocation functions are used to create an invocation reference, set the parameters for the call, add any settings, such as action headers or debug parameters, and invoke the operation (which serializes the output, makes the call, gets the response, and deserializes the reply). Additional functions allow you to schedule the invocation on your run loop (recommended), set a callback to deal with the response, and add a custom serializer or deserializer.

Protocol Handler Functions

The protocol handler functions assist in the serialization and deserialization of service requests and responses. In other words, they translate between XML messages and dictionaries. These functions can be used to support either server-side or client-side web services applications. On the client side, they are not generally needed, as serialization and deserialization are handled by the method invocation, but they can be useful when this work needs to be done separately from the method invocation itself.

Web Services Types Functions

Web Services types functions translate between WSTypes and CFTypes. Because CFTypes are determined at runtime, it isn't always possible to produce a static mapping between Core Foundation types and the corresponding serialized XML types used to interact with remote servers. What this means is that when converting between serialized XML data and deserialized CFTypes, you need to do a conversion from WSTypes to CFTypes, and vice versa.

Functions

WSGetCFTypeIDFromWSTypeID

Gets the CFType associated with a given WSType

   WSGetCFTypeIDFromWSTypeID(
   WSTypeID typeID);

Parameters
typeID

The WSTypeID for which you need a CFTypeID.

Return Value

Returns a CFTypeID, or 0 if not found

Discussion

Returns the CFTypeID that is associated with a given WSTypeID. CFTypeIDs are only valid during a particular instance of a process and should not be used as static values.

Availability
Declared In
WSTypes.h

WSGetWSTypeIDFromCFType

Returns the WSTypeID associated with a given CFTypeRef.

   WSGetWSTypeIDFromCFType(
   CFTypeRef ref);

Parameters
ref

A CFTypeRef object. An actual instance of a CFType must be passed.

Return Value

the WSTypeID used in serializing the object. If no WSTypeID matches, eWSUnknownType is returned.

Discussion

Returns the WSTypeID associated with CFTypeRef. Because there is not a one to one mapping between CFTypeID and WSTypesID an actual instance of a CFType must be passed.

Availability
Declared In
WSTypes.h

WSMethodInvocationAddDeserializationOverride

Specifies a callback to be made when parsing the XML in a method response.

   WSMethodInvocationAddDeserializationOverride(
   WSMethodInvocationRef invocation,
   CFStringRef typeNamespace,
   CFStringRef typeName,
   WSMethodInvocationDeserializationProcPtr deserializationProc,
   WSClientContext *context);

Parameters
invocation

The method invocation reference.

typeNamespace

The fully resolved namespace for a specific type. For example, this field could be: CFSTR("http://www.Myserver.com/myNameSpace"). If NULL, the default namespace will be used.

typeName

The non-qualified type name. Note that this is the XML /name/ to be deserialized, not the name of the type. For example, if the XML is <Sharename xsi:type="xsd:string">Album-9</Sharename>, the typeName is Sharename, not string. This parameter must not be NULL.

deserializationProc

A ProcPtr to the callback to be called to perform the deserialization.

context

A pointer to a WSClientContext. The structure will be copied.

Discussion

Specifies a callback to be made when parsing an XML method response. Used to deserialize types the default deserializer does not handle. The callback should return a CFTypeRef containing the deserialized object value. If the callback returns NULL, the default deserializer is used.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationAddSerializationOverride

Specifies a callback to be made when creating the XML for an method invocation.

   WSMethodInvocationAddSerializationOverride(
   WSMethodInvocationRef invocation,
   CFTypeID objType,
   WSMethodInvocationSerializationProcPtr serializationProc,
   WSClientContext *context);

Parameters
invocation

The invocation currently being serialized

objType

The CFTypeID of the object to serialize

serializationProc

The ProcPtr to the callback

context

A pointer to a WSClientContext. The structure will be copied.

Discussion

Specifies a callback which will be called to produce the XML that represents the serialization of a given type ref. See WSTypes.h for a list of CFTypes for which there are default serializers. If your callback returns NULL, the default serializer will be used.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationCopyParameters

Creates a copy of the parameters dictionary and sets the order in an array.

   WSMethodInvocationCopyParameters(
   WSMethodInvocationRef invocation,
   CFArrayRef *parameterOrder);  /* can be NULL */

Parameters
invocation

the invocation

parameterOrder

a pointer to a CFArray which will will receive the names, in their specified order, of the input parameter values. This parameter may be NULL.

Return Value

a CFDictionaryRef

Discussion

Copies the parameters from the invocation. The resulting dictionary contains the parameter dictionary. The parameterOrder output parameter, if not NULL, will contain the order used to serialize the parameters.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationCopyProperty

Creates a copy of a named property of the invocation reference.

   WSMethodInvocationCopyProperty(
   WSMethodInvocationRef invocation,
   CFStringRef propertyName);

Parameters
invocation

The method invocation.

propertyName

The name of the property to retrieve.

Return Value

the CFTypeRef value of the property, or NULL if the property was not specified.

Discussion

Returns a property from an invocation. If the result is NULL, the property doesn't exist. Being a copy call, you must release the result.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationCopySerialization

Creates an XML serialization of a method invocation.

   WSMethodInvocationCopySerialization(
   WSMethodInvocationRef invocation);

Parameters
invocation

The invocation to serialize.

Return Value

A CFDataRef of the serialized XML method invocation.

Discussion

Creates a serialized version of the method invocation which can be used at a later time.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationCreate

Creates a reference to a method invocation, containing the URL of the service, the operation name, and the protocol.

   WSMethodInvocationCreate(
   CFURLRef url,
   CFStringRef methodName,
   CFStringRef protocol);

Parameters
url

The endpoint of the service.

methodName

The name of the operation to be called.

protocol

A string defined above that determines the type of invocation object to create. There are string constants for XML-RPC, SOAP 1.1, or SOAP 1.2. Other protocols are not recognized.

Return Value

A WSMethodInvocationRef object that can be passed to WSMethodInvocationInvoke or scheduled with a run loop.

Discussion

Creates a web services method invocation object. This is the fundamental object used when passing method parameters or settings, callbacks, or custom serializers or deserializers. This object may be executed synchronously using WSMethodInvocationInvoke or scheduled on a run loop for asynchronous execution using WSMethodInvocationScheduleWithRunLoop.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationCreateFromSerialization

Creates a method invocation object from an XML serialization.

   WSMethodInvocationCreateFromSerialization(
   CFDataRef contract);

Parameters
contract

The result of a previously serialized WSMethodInvocationRef.

Return Value

A WSMethodInvocationRef object that can be passed to WSMethodInvocationInvoke or scheduled with a run loop.

Discussion

Creates a web services method invocation object from a previously serialized contract. You can use this with a serialization returned from WSMethodInvocationCopySerialization.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationGetTypeID

Returns the type ID of the current method invocation.

   WSMethodInvocationGetTypeID(
   void);

Return Value

A CFTypeID.

Discussion

Returns the ID of the current method invocation. You should call this immediately after creating the invocation reference.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationInvoke

Invokes an web services operation synchronously.

   WSMethodInvocationInvoke(
   WSMethodInvocationRef invocation);

Parameters
invocation

The method invocation reference.

Return Value

a CFDictionaryRef containing the result of the execution or a fault, and optional debug information.

Discussion

Executes the invocation synchronously. If the call was successful, the result contains the result of the invocation. If the invocation failed for any reason, including out of memory or invalid parameter errors, then the result contains a fault structure. You must release the result when you are done with it. To execute the invocation asynchronously (recommended), use WSMethodInvocationScheduleWithRunLoop.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationScheduleWithRunLoop

Schedule a method invocation for asynchronous execution on a run loop.

   WSMethodInvocationScheduleWithRunLoop(
   WSMethodInvocationRef invocation,
   CFRunLoopRef runLoop,
   CFStringRef runLoopMode);

Parameters
invocation

The method invocation reference.

runLoop

The run loop upon which to schedule the invocation.

runLoopMode

The run loop mode.

Discussion

Schedules the invocation to execute on the run loop. You must also set a callback to handle the response, using WSMethodInvocationSetCallBack. This is the recommended way to invoke web services, due to the unpredictable network delays inherent in such operations.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationSetCallBack

Set a callback to handle the response to an asynchronous method invocation.

   WSMethodInvocationSetCallBack(
   WSMethodInvocationRef invocation,
   WSMethodInvocationCallBackProcPtr clientCB,
   WSClientContext *context);

Parameters
invocation

The method invocation reference.

clientCB

A ProcPtr to be called when the invocation completes.

context

A pointer to a WSClientContext. The structure will be copied.

Discussion

Sets the callback to handle the response for an asynchronous method invocation. The callback is passed a reference to the method invocation just completed, a pointer to private data, and a dictionary that contains the return values for the operation or a fault structure. Test for a fault using WSMethodResultIsFault. The callback parses the method response dictionary, which contains the deserialized return data, and may contain the raw XML of the return message as well. The callback is responsible for releasing the result ref.

Call with a clientCB and context of NULL to clear the invocation callback.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationSetParameters

Set the parameter names, types, and order for a method invocation.

   WSMethodInvocationSetParameters(
   WSMethodInvocationRef invocation,
   CFDictionaryRef parameters,
   CFArrayRef parameterOrder);  /* can be NULL */

Parameters
invocation

The invocation reference.

parameters

A CFDictionaryRef of CFString keys and CFTypeRef values.

parameterOrder

A CFArrayRef of CFString parameter names in order for XML-RPC.

Discussion

Sets the parameters for a method invocation. The parameters dictionary should contain the names and types of the parameters. The parameter order array should contain the names of the parameters in the order they should be passed. The parameterOrder may be NULL, in which case the order of the parameters is undefined. If the parameters dictionary contains more or fewer parameters than are specified by the order, the behavior is undefined.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationSetProperty

Sets a named property of the method invocation.

   WSMethodInvocationSetProperty(
   WSMethodInvocationRef invocation,
   CFStringRef propertyName,
   CFTypeRef propertyValue);

Parameters
invocation

The method invocation reference.

propertyName

A CFStringRef name of the property to set.

propertyValue

A CFTypeRef containing the new property value.

Discussion

Adds properties to a method invocation. These properties can be user-defined or one of the declared properties, which may alter the behavior of the invocation. Declared properties start with the string "kWS," for example kWSHTTPFollowsRedirects. Use these properties to add SOAP action headers or to set debug properties, such as including the raw XML in the method response dictionary. Properties are serialized along with the contract, so you should avoid using raw pointers in a CFNumber, for example.

Availability
Declared In
WSMethodInvocation.h

WSMethodInvocationUnscheduleFromRunLoop

Unschedules a method invocation from a run loop.

   WSMethodInvocationUnscheduleFromRunLoop(
   WSMethodInvocationRef   invocation,
   CFRunLoopRef            runLoop,
   CFStringRef             runLoopMode);

Parameters
invocation

The method invocation reeference.

runLoop

The run loop from which to unschedule the invocation.

runLoopMode

The run loop mode.

Discussion

Unschedules the invocation from a given run loop and mode. If the invocation has not yet completed, its callback will not be called.

Availability
Declared In
WSMethodInvocation.h

WSMethodResultIsFault

Tests a method result dictionary for a fault condition.

WSMethodResultIsFault (CFDictionaryRef methodResult);

Parameters
methodResult

A method result dictionary.

Return Value

A boolean TRUE if the result contains a fault condition.

Discussion

If the result is a fault, look in the kWSFaultCode, kWSFaultString, and kWSFaultExtra fields of the dictionary. If not a fault, kWSMethodInvocationResult will contain the result of the execution. If debugging information was requested, it will be available in the dictionary as well.

Availability
Declared In
WSMethodInvocation.h

WSProtocolHandlerCopyFaultDocument

Creates a Fault XML response for a given WSProtocolHandler and fault details dictionary.

   WSProtocolHandlerCopyFaultDocument(
   WSProtocolHandlerRef ref,
   CFDictionaryRef methodContext,
   CFDictionaryRef faultDict);

Parameters
ref

A WSProtocolHandlerRef, as created by WSProtocolHandlerCreate.

methodContext

The CFDictionary containing the context for this method call, as returned by WSProtocolHandlerParseRequest.

faultDict

A CFDictionary containing the fault information. See WSMethodInvocation.h for valid keys.

Return Value

A CFDataRef containing the XML fault.

Discussion

This function creates a Fault XML response for a given WSProtocolHandlerRef and fault details dictionary. The fault dictionary contains one or more of kWSFaultString, kWSFaultCode or kWSFaultExtra, as per WSMethodInvocation.h.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerCopyProperty

Returns a copy of a property from a protocol handler reference.

   WSProtocolHandlerCopyProperty(
   WSProtocolHandlerRef ref,
   CFStringRef propertyName);

Parameters
ref

A WSProtocolHandlerRef, as created by WSProtocolHandlerCreate.

propertyName

The name of the property to copy.

Return Value

The CFTypeRef value of the property, or NULL if the specified property does not exist.

Discussion

Returns a property from a protocol handler. If the result is NULL, the property doesn't exist. Since this is a Copy call, you must release the result.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerCopyReplyDictionary

Parses an incoming XML document as if it were the reply of a method.

   WSProtocolHandlerCopyReplyDictionary(
   WSProtocolHandlerRef ref,
   CFStringRef methodName,
   CFDataRef data);

Parameters
ref

A WSProtocolHandlerRef, as created by WSProtocolHandlerCreate.

methodName

The method name to treat the XML file as a result of.

data

A CFDataRef of the XML document to parse

Return Value

A CFDictionary, as returned by WSMethodInvocationInvoke.

Discussion

Parse an incoming XML document as if it were the reply of a method. The results are the same as the WSMethodInvocationInvoke response; the reply could be a fault. If there was a parse error, NULL is returned. Protocol specific additions, such as kWSSOAPMessageHeaders, may also be present in the dictionary. The caller must release the resulting dictionary.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerCopyReplyDocument

Creates a Reply XML document for a given WS ProtocolHandler and context dictionary.

   WSProtocolHandlerCopyReplyDocument(
   WSProtocolHandlerRef ref,
   CFDictionaryRef methodContext,
   CFTypeRef resultValue);

Parameters
ref

The WSProtocolHandler to respond.

methodContext

The CFDictionary containing the context for this method call, as returned by WSProtocolHandlerParseRequest.

resultValue

A CFTypeRef representing the data to be serialized.

Return Value

A CFDataRef containing the XML response.

Discussion

This function creates a Reply XML document for a given WSProtocolHandler and context dictionary. Protocol specific addtions (for example, kWSSOAPMessageHeaders) may also be present in the dictionary.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerCopyRequestDictionary

Parses an incoming XML document for the method name and parameters.

   WSProtocolHandlerCopyRequestDictionary(
   WSProtocolHandlerRef ref,
   CFDataRef data);

Parameters
ref

The protocol handler to use.

data

The XML document to parse.

Return Value

A CFDictionary.

Discussion

This function parses an incoming XML document for the method name and parameters. The results are in a dictionory as kWSMethodName (a CFString), kWSMethodParameters (a CFDictionary), and kWSMethodParameterOrder (a CFArray). If a parse error occurred, NULL is returned. Protocol specific additions (for example, kWSSOAPMessageHeaders) may also be present in the dictionary. The dictionary returned also represents the context with which XML reply documents are created (see WSProtocolHandlerCreateReply). The caller must release the resulting dictionary. Note that the returned dictionary should be used as an input parameter for other WSProtocol functions that require a context dictionary parameter.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerCopyRequestDocument

Creates an XML request for a given WSProtocolHandler and parameter list.

   WSProtocolHandlerCopyRequestDocument(
   WSProtocolHandlerRef ref,
   CFStringRef methodName,
   CFDictionaryRef methodParams,
   CFArrayRef methodParamOrder,
   CFDictionaryRef methodExtras);

Parameters
ref

The WSProtocolHandlerRef.

methodName

A CFString of the method name to call.

methodParams

A CFDictionary containing the parameters to send.

methodParamOrder

A CFArray, which, if not NULL, specifies the order of the parameters in the CFDictionary.

methodExtras

A CFDictionary, which, if not NULL, contains additional information for the protocol (for example, kWSSoapMessageHeaders).

Return Value

A CFDataRef.

Discussion

This function creates an XML request for a given WSProtocolHandler and parameter list. This is the request sent to a server.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerCreate

Creates a WSProtocolHandlerRef for use in translating an XML document.

   WSProtocolHandlerCreate(
   CFAllocatorRef allocator,
   CFStringRef protocol);

Parameters
allocator

A CFAllocatorRef used to allocate the protocol handler.

protocol

A constant string, defined in WSMethodInvocation.h, that determines the type of implementation to create (XML-RPC vs. SOAP).

Return Value

A WSProtocolHandlerRef; NULL if a parse error occurred.

Discussion

This function creates a WSProtocolHandlerRef for use in translating an XML document. A protocol handler translates dictionaries into web services requests. It is created with a string specifying the protocol (XML-RPC or SOAP) and can be modified by setting various properties. It should be noted that the parser can be re-used for multiple parses.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerGetTypeID

Returns a CFTypeID for the current WSProtocolHandlerRef.

   WSProtocolHandlerGetTypeID(
   void);

Return Value

A CFTypeID.

Discussion

Returns the CFTypeID of the opaque WSProtocolHandlerRef most recently created by WSProtocolHandlerCreate. CFTypeIDs are only valid during a particular instance of a process and should not be used as static values.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerSetDeserializationOverride

Specifies a callback to be made when parsing an XML method response.

   WSProtocolHandlerSetDeserializationOverride(
   WSProtocolHandlerRef protocol,
   CFStringRef typeNamespace,
   CFStringRef typeName,
   WSProtocolHandlerDeserializationProcPtr deserializationProc,
   WSClientContext *context);

Parameters
protocol

The ProtocolHandlerRef.

typeNamespace

The fully resolved namespace for a specific type. If NULL, the default namespace will be used. For example, this field could be: CFSTR("http://www.w3.org/2001/XMLSchema-instance").

typeName

The non-qualified type name. This parameter must not be NULL.

deserializationProc

A ProcPtr to be called to perform the deserialization.

context

A pointer to a WSClientContext. The structure will be copied.

Discussion

This function specifies a callback to be made when parsing an XML method response. The callback is passed a reference to the protocol element currently being executed, the root of the response parse tree, the current node being deserialized, and a pointer to private data. The return result should be a valid CFTypeRef object, which will be released by the caller. If the callback returns NULL, the default deserializer will be used.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerSetProperty

Sets a property in a specified protocol handler.

   WSProtocolHandlerSetProperty(
   WSProtocolHandlerRef ref,
   CFStringRef propertyName,
   CFTypeRef propertyValue);

Parameters
ref

The protocol handler.

propertyName

The name of the property to set.

propertyValue

The value of the property to set.

Discussion

This function sets the value of a named property in a method implementation.

Availability
Declared In
WSProtocolHandler.h

WSProtocolHandlerSetSerializationOverride

Specifies a callback which will be called to produce the XML that represents the serialization of a given type ref.

   WSProtocolHandlerSetSerializationOverride(
   WSProtocolHandlerRef protocol,
   CFTypeID objType,
   WSProtocolHandlerSerializationProcPtr serializationProc,
   WSClientContext *context);

Parameters
protocol

The protocol which is to be executed.

objType

The CFTypeID of the object to be serialized.

serializationProc

The serialization callback that will do the work.

context

A pointer to a WSClientContext. The structure will be copied.

Discussion

This function specifies a callback which will be called to produce the XML that represents the serialization of a given type ref. This callback is called whenever a type has the given CFTypeID. The callback should return an XML snippet that will be understood by the server as a correct serialization for a given type. If the callback returns NULL, the default serializer is used. For SOAP serializations, the parameter key (element name) is not part of the callback; it will be substituded for all occurances of "%@" in the returned string. If your callback returns NULL, the default serializer will be used.

Availability
Declared In
WSProtocolHandler.h

Hide TOC

© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-01-06)

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.