Web Services Core Reference

Framework
WebServicesCore.framework, CoreServices.framework
Companion guide
Declared in
WSMethodInvocation.h
WSProtocolHandler.h
WSTypes.h

Overview

The Web Services Core framework provides client-side support for accessing web services using XML over HTTP or HTTPS, with specific support for XML-RPC, SOAP 1.1, and SOAP 1.2 protocols. Some server-side support is also provided, with protocol handlers for serializing and deserializing data in SOAP or XML-RPC format.

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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
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
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.8.
Declared In
WSProtocolHandler.h

Callbacks by Task

Context Callbacks

Several calls in Web Services Core take a callback with an optional context pointer. The context is copied and the info pointer is retained. When the callback is made, the info pointer is passed to the callback.

Method Invocation Callbacks

Protocol Handler Callbacks

Callbacks

WSClientContextCopyDescriptionCallBackProcPtr

This is the callback that copies the information.

typedef CALLBACK_API( CFStringRef *, WSClientContextCopyDescriptionCallBackProcPtr )
   (void * info);

If your callback is named MyInfoCopyCallback, declare it like this:

   CFStringRef MyInfoCopyCallback (
   void *info);

Parameters
info

Private callback data to be coped.

Return Value

A CFStringRef containing the client context information.

Discussion

Your callback is passed a a pointer to private data for you to copy.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSTypes.h

WSClientContextReleaseCallBackProcPtr

This is the callback that releases the information.

typedef CALLBACK_API( void *, WSClientContextReleaseCallBackProcPtr )
   (void * info);

If your callback is named MyInfoReleaseCallback, declare it like this:

   void MyInfoReleaseCallback (
   void *info);

Parameters
info

Private callback data to be released.

Discussion

Your callback is passed a a pointer to private data for you to release.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSTypes.h

WSClientContextRetainCallBackProcPtr

This is the callback that retains the information.

typedef CALLBACK_API( void *, WSClientContextRetainCallBackProcPtr )
   (void * info);

If your callback is named MyInfoRetainCallback, declare it like this:

   void MyInfoRetainCallback (
   void *info);

Parameters
info

Private callback data to be retained.

Discussion

Your callback is passed a a pointer to private data for you to retain.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSTypes.h

WSMethodInvocationCallBackProcPtr

This is the callback that handles method invocation completion when the method is invoked asynchronously.

typedef CALLBACK_API( void , WSMethodInvocationCallBackProcPtr )
   (WSMethodInvocationRef invocation,
   void *info,
   CFDictionaryRef outRef);

If your callback is named MyCompletionCallback, declare it like this:

   void MyCompletionCallback (
   WSMethodInvocationRef invocation,
   void *info,
   CFDictionaryRef outRef);

Parameters
invocation

The method invocation for which this callback handles completion.

info

Private callback data.

outRef

A CFDictionaryRef containing the method invocation result or a fault structure, and optional debug information.

Discussion

Your callback is passed a reference to the invocation just completed, a pointer to private data, and a dictionary that contains the return value or falut for this invocation. The callback is responsible for releasing the dictionary when it is no longer used.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSMethodInvocation.h

WSMethodInvocationDeserializationProcPtr

This is an optional callback that handles custom deserialization of a particular data type for a method response.

typedef CALLBACK_API( CFTypeRef ,
   WSMethodInvocationDeserializationProcPtr )
   (WSMethodInvocationRef invocation,
   CFXMLTreeRef msgRoot,
   CFXMLTreeRef deserializeRoot,
   void *info);

If your callback is named MyDeserilaizerCallback, declare it like this:

   CFTypeRef MyDeserilaizerCallback (
   WSMethodInvocationRef invocation,
   CFXMLTreeRef msgRoot,
   CFXMLTreeRef deserializeRoot,
   void *info);

Parameters
invocation

The method invocation for which this callback handles deserialization.

msgRoot

The root element of the XML to be deserialized.

deserializeRoot

The tree element of the XML to be deserialized.

info

Private callback data.

Return Value

A CFTypeRef representing the deserialized data. The caller will release this data. If you return NULL, the default deserializer is used.

Discussion

This callback is passed a reference to the invocation 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) or NULL to allow the default deserializer to act. Unlike the serialization callback, which is called only for a specified data type, the deserialization callback is called for every element to be deserialized.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSMethodInvocation.h

WSMethodInvocationSerializationProcPtr

This is an optional callback that handles custom serialization of a particular data type for method invocation.

typedef CALLBACK_API( CFStringRef , WSMethodInvocationSerializationProcPtr )
   (WSMethodInvocationRef invocation,
   CFTypeRef obj,
   void *info);

If your callback is named MySerilaizerCallback, declare it like this:

   CFStringREf MySerilaizerCallback (
   WSMethodInvocationRef invocation,
   CFTypeRef obj,
   void *info);

Parameters
invocation

The method invocation for which this callback handles serialization.

obj

The CFTypeRef for which this callback produces serialized XML.

info

Private callback data.

Return Value

A CFStringRef containing valid XML. The caller of this callback will release the string. If you return NULL, the default serializer is used.

Discussion

This callback is called whenever a type to be serialized by the method invocation 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.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSMethodInvocation.h

WSProtocolHandlerDeserializationProcPtr

This is an optional callback that handles custom deserialization of a particular data type for a protocol handler.

typedef CALLBACK_API( CFTypeRef ,
   WSProtocolHandlerDeserializationProcPtr )
   (WSProtocolHandlerRef protocol,
   CFXMLTreeRef msgRoot,
   CFXMLTreeRef deserializeRoot,
   void *info);

If your callback is named MyDeserilaizerCallback, declare it like this:

   CFTypeRef MyDeserilaizerCallback (
   WSProtocolHandlerRef protocol,
   CFXMLTreeRef msgRoot,
   CFXMLTreeRef deserializeRoot,
   void *info);

Parameters
protocol

The protocol handler for which this callback handles deserialization.

msgRoot

The root element of the XML to be deserialized.

deserializeRoot

The tree element of the XML to be deserialized.

info

Private callback data.

Return Value

A CFTypeRef representing the deserialized data. The caller will release this data. If you return NULL, the default deserializer is used.

Discussion

This callback is passed a reference to the invocation 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) or NULL to allow the default deserializer to act. Unlike the serialization callback, which is called only for a specified data type, the deserialization callback is called for every element to be deserialized.

Availability
  • Available in OS X v10.3 and later.
Declared In
WSProtocolHandler.h

WSProtocolHandlerSerializationProcPtr

This is an optional callback that handles custom serialization of a particular data type for a protocol handler.

typedef CALLBACK_API( CFStringRef , WSProtocolHandlerSerializationProcPtr )
   (WSProtocolHandlerRef protocol,
   CFTypeRef obj,
   void *info);

If your callback is named MySerilaizerCallback, declare it like this:

   CFStringREf MySerilaizerCallback (
   WSProtocolHandlerRef protocol,
   CFTypeRef obj,
   void *info);

Parameters
protocol

The protocol handler for which this callback handles serialization.

obj

The CFTypeRef for which this callback produces serialized XML.

info

Private callback data.

Return Value

A CFStringRef containing valid XML. The caller of this callback will release the string. If you return NULL, the default serializer is used.

Discussion

This callback is called whenever a type to be serialized by the protocol handler 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.

Availability
  • Available in OS X v10.3 and later.
Declared In
WSProtocolHandler.h

Data Types

WSClientContext

An optional context that can contain data you want passed to your callback.

struct WSClientContext {
      CFIndex             version;
      void *              info;
      WSClientContextRetainCallBackProcPtr  retain;
      WSClientContextReleaseCallBackProcPtr  release;
      WSClientContextCopyDescriptionCallBackProcPtr  copyDescription;
};
typedef struct WSClientContext          WSClientContext;
Fields
version

Set to zero.

info

A pointer to your information to be passed to your callback.

retain

Callback made on the info pointer. This field may be NULL.

release

Callback made on the info pointer. This field may be NULL.

copyDescription

Callback made on the info pointer. This field may be NULL.

Discussion

Several calls in the Web Services Core framework take a callback with an optional context pointer. The context is copied and the info pointer retained. When the callback is made, the info pointer is passed to the callback.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSTypes.h

WSMethodInvocationRef

An opaque reference to a web services method invocation.

typedef struct OpaqueWSMethodInvocationRef*  WSMethodInvocationRef;
Discussion

The WSMethodInvocationRef is the fundamental object of web services. Create it using WSMethodInvocationCreate. Use it to set parameters, callbacks, and settings for a method invocation, and to invoke a method and obtain a response.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSMethodInvocation.h

WSProtocolHandlerRef

An opaque reference to a web services protocol handler.

typedef struct OpaqueWSProtocolHandlerRef*  WSProtocolHandlerRef;
Discussion

The WSProtocolHandlerRef represents an instance of a protocol handler. Create it using WSProtocolHandlerCreate.

Availability
  • Available in OS X v10.2 and later.
Declared In
WSProtocolHandler.h

Constants

WSTypes Constants

WSTypeID

Web Services Core uses the following enumeration when serializing between Core Foundation and XML types. Because CFTypes are defined at runtime, it isn't always possible to produce a static mapping to a particular CFTypeRef. This enum and associated API allows for static determination of the expected serialization.

enum WSTypeID {
   eWSUnknownType                = 0,
   eWSNullType                   = 1,
   eWSBooleanType                = 2
   eWSIntegerType                = 3,
   eWSDoubleType                 = 4,
   eWSStringType                 = 5,
   eWSDateType                   = 6,
   eWSDataType                   = 7,
   eWSArrayType                  = 8
   eWSDictionaryType             = 9};
Constants
eWSUnknownType

No mapping is known for this type.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSNullType

Maps to CFNullRef.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSBooleanType

Maps to CFBooleanRef.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSIntegerType

Maps to CFNumberRef for 8, 16, 32 bit integers.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSDoubleType

Maps to CFNumberRef for long, double, or real numbers.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSStringType

Maps to CFStringRef.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSDateType

Maps to CFDateRef.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSDataType

Maps to CFDataRef.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSArrayType

Maps to CFArrayRef.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

eWSDictionaryType

Maps to CFDictionaryRef.

Available in OS X v10.2 and later.

Declared in WSTypes.h.

String Constants

Protocol Constants

Pass these constants as arguments for supported protocols when creating a method invocation or protocol handler reference.

CFStringRef kWSXMLRPCProtocol;
CFStringRef kWSSOAP1999Protocol;
CFStringRef kWSSOAP2001Protocol;
Constants
kWSXMLRPCProtocol

XML-RPC protocol.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSTypes.h.

kWSSOAP1999Protocol

SOAP v1.1 protocol.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSTypes.h.

kWSSOAP2001Protocol

SOAP v1.2 protocol.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSTypes.h.

Result and Fault Constants

These string constants identify method results, faults, or network problems.

CFStringRef kWSMethodInvocationResult;
CFStringRef kWSFaultString;
CFStringRef kWSFaultCode;
CFStringRef kWSFaultExtra;
CFStringRef kWSNetworkStreamFaultString;
CFStringRef kWSStreamErrorMessage;
CFStringRef kWSStreamErrorDomain;
CFStringRef kWSStreamErrorError;
Constants
kWSMethodInvocationResult

Dictionary entry if the invocation result is not a fault. If you don't know what field to ask for, you can ask for this key. You can also specify the name of a reply parameter in the invocation using kWSMethodInvocationResultParameterName. This will add an alias for the given name to the result dictionary so that this key will return the named parameter.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSFaultString

If the result is a fault, this key returns a CFString with the fault type. If the fault type is kWSNetworkStreamFaultString, then the fault is a network error. In the case of a network error, kWSFaultCode should be ignored, and kWSFaultExtra returns a dictionary indicating the network error.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSFaultCode

If the result is a fault, this key returns a CFNumber with the fault code, unless the fault is a network error, in which case this field should be ignored.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSFaultExtra

If the result is a fault, and the fault is a network error, the key returns a CFDictionary with the network error. This key may also return a CFString, or NULL.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSNetworkStreamFaultString

If kWSFaultExtra is a dictionary, this key returns a CFString from that dictionary for debug purposes.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSStreamErrorMessage

If kWSFaultExtra is a dictionary, this key returns a CFString from that dictionary containing the stream error message.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSStreamErrorDomain

If kWSFaultExtra is a dictionary, this key returns a CFNumberRef from that dictionary containing domain number. See CFStream.h for domain numbers.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSStreamErrorError

If kWSFaultExtra is a dictionary, this key returns a CFNumberRef from that dictionary containing error number. See CFStream.h for error numbers.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

HTTP Message Constants

You can specify a CFHTTPMessageRef as a property to be used instead of creating a new outgoing HTTP or HTTPS message for method invocations. The CFHTTPMessageRef can contain header, proxy, and authentication information. The body of the message will be ignored and replaced with the outgoing, serialized invocation. After the invocation has executed, you can retrieve a copy of the actual CFHTTPMessageRef, containing the details of the invocation from the reply dictionary by using kWSHTTPResponseMessage as a key. Attempting to retrieve the response message property before the invocation completes will return NULL.

CFStringRef kWSHTTPMessage;
CFStringRef kWSHTTPResponseMessage;
Constants
kWSHTTPMessage

The message.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSHTTPResponseMessage

The key used to retrieve the response from the reply dictionary..

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

HTTP Message Propereties

To avoid having to create an entire CFHTTPMessageRef, these properties are individually settable. If they are set, they will override any CFHTTPMessageRef previously specified.

CFStringRef kWSHTTPVersion;
CFStringRef kWSHTTPExtraHeaders;
CFStringRef kWSHTTPProxy;
CFStringRef kWSHTTPFollowsRedirects;
Constants
kWSHTTPVersion

The CFHTTPMessageRef version such as “http/1.1”.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSHTTPExtraHeaders

A CFDictionary of { key (CFString), val (CFString) } pairs.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSHTTPProxy

The CFURLRef of the SOCKS proxy.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSHTTPFollowsRedirects

A CFBoolean that controls whether the invocation follows redirects (default is false).

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

Debug Properties

These flags will populate the WSInvocationResultRef with debugging information. The property name of the flag is the same as the the field in the result dictionary.

CFStringRef kWSDebugOutgoingHeaders;
CFStringRef kWSDebugOutgoingBody;
CFStringRef kWSDebugIncomingHeaders;
CFStringRef kWSDebugIncomingBody;
Constants
kWSDebugOutgoingHeaders

If this flag is set, the result includes the outgoing message headers.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSDebugOutgoingBody

If this flag is set, the result includes the outgoing message body.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSDebugIncomingHeaders

If this flag is set, the result includes the incoming message headers.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSDebugIncomingBody

If this flag is set, the result includes the incoming message body.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

SOAP Message Properties

This is an array of CFStringRefs which contain valid XML header elements that are sent with the message. These are only applicable to the header of a SOAP message.

CFStringRef kWSSOAPMessageHeaders;
Constants
kWSSOAPMessageHeaders

A CFArrayRef of XML header elements, as CFStringRefs.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

Message Modifier Properties

When serializing a dictionary, setting these properties can modify the behavior of the serialization.

CFStringRef kWSRecordParameterOrder;
CFStringRef kWSRecordNamespaceURI;
CFStringRef kWSRecordType;
Constants
kWSRecordParameterOrder

A CFArrayRef of CFStringRefs containing the parameter names, in order.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSRecordNamespaceURI

A CFStringRef containing the namespace.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

kWSRecordType

A CFStringRef containing the record type.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

Result Parameter Name

You can force the deserializer to create an alias to a parameter as the invocation result by setting the parameter name.

CFStringRef kWSMethodInvocationResultParameterName;
Constants
kWSMethodInvocationResultParameterName

Set this property to create an alias to a parameter to be returned by kWSMethodInvocationResult. Pass in the parameter name as a CFStringRef.

Available in OS X v10.2 and later.

Deprecated in OS X v10.8.

Declared in WSMethodInvocation.h.

Result Codes

Result CodeValueDescription
errWSInternalError-65793L

An internal framework error occured.

Available in OS X v10.2 and later.

errWSTransportError-65794L

A network error occured.

Available in OS X v10.2 and later.

errWSParseError-65795L

The server response was not valid XML.

Available in OS X v10.2 and later.

errWSTimeoutError-65796L

The method invocation timed out.

Available in OS X v10.2 and later.