Mac Developer Library

Developer

WebServicesCore.framework, CoreServices Framework Reference Web Services Core Reference

Options
Deployment Target:

On This Page

Web Services Core Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import CoreServices;

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

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.

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

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFDictionaryRef WSMethodInvocationCopyParameters ( WSMethodInvocationRef invocation, CFArrayRef *parameterOrder );

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFTypeRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Creates an XML serialization of a method invocation.

    Declaration

    Objective-C

    CFDataRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    WSMethodInvocationRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Creates a method invocation object from an XML serialization.

    Declaration

    Objective-C

    WSMethodInvocationRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Returns the type ID of the current method invocation.

    Declaration

    Objective-C

    CFTypeID 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Invokes an web services operation synchronously.

    Declaration

    Objective-C

    CFDictionaryRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    void WSMethodInvocationSetParameters ( WSMethodInvocationRef invocation, CFDictionaryRef parameters, CFArrayRef parameterOrder );

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Sets a named property of the method invocation.

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Unschedules a method invocation from a run loop.

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Tests a method result dictionary for a fault condition.

    Declaration

    Objective-C

    Boolean 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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.

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

    Declaration

    Objective-C

    CFDataRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFTypeRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFDictionaryRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFDataRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFDictionaryRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFDataRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

  • Creates a WSProtocolHandlerRef for use in translating an XML document.

    Declaration

    Objective-C

    WSProtocolHandlerRef 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

  • Returns a CFTypeID for the current WSProtocolHandlerRef.

    Declaration

    Objective-C

    CFTypeID 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

  • Sets a property in a specified protocol handler.

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    void 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

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.

  • Gets the CFType associated with a given WSType

    Declaration

    Objective-C

    CFTypeID 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Returns the WSTypeID associated with a given CFTypeRef.

    Declaration

    Objective-C

    WSTypeID 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

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.

  • This is the callback that retains the information.

    Declaration

    Objective-C

    typedef CALLBACK_API( void *, WSClientContextRetainCallBackProcPtr ) (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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

  • This is the callback that releases the information.

    Declaration

    Objective-C

    typedef CALLBACK_API( void *, WSClientContextReleaseCallBackProcPtr ) (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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

  • This is the callback that copies the information.

    Declaration

    Objective-C

    typedef CALLBACK_API( CFStringRef *, WSClientContextCopyDescriptionCallBackProcPtr ) (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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Objective-C

    typedef CALLBACK_API( void , WSMethodInvocationCallBackProcPtr ) ( 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Objective-C

    typedef CALLBACK_API( CFStringRef , WSMethodInvocationSerializationProcPtr ) ( 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Objective-C

    typedef CALLBACK_API( CFTypeRef , WSMethodInvocationDeserializationProcPtr ) ( 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Objective-C

    typedef CALLBACK_API( CFStringRef , WSProtocolHandlerSerializationProcPtr ) ( 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Objective-C

    typedef CALLBACK_API( CFTypeRef , WSProtocolHandlerDeserializationProcPtr ) ( 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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.3 and later.

Data Types

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

    Declaration

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

  • An opaque reference to a web services method invocation.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

  • An opaque reference to a web services protocol handler.

    Declaration

    Objective-C

    typedef struct OpaqueWSProtocolHandlerRef* WSProtocolHandlerRef;

    Discussion

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

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

Constants

WSTypes Constants

  • 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.

    Declaration

    Objective-C

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

    Constants

    • eWSUnknownType

      eWSUnknownType

      No mapping is known for this type.

      Available in OS X v10.2 and later.

    • eWSNullType

      eWSNullType

      Maps to CFNullRef.

      Available in OS X v10.2 and later.

    • eWSBooleanType

      eWSBooleanType

      Maps to CFBooleanRef.

      Available in OS X v10.2 and later.

    • eWSIntegerType

      eWSIntegerType

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

      Available in OS X v10.2 and later.

    • eWSDoubleType

      eWSDoubleType

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

      Available in OS X v10.2 and later.

    • eWSStringType

      eWSStringType

      Maps to CFStringRef.

      Available in OS X v10.2 and later.

    • eWSDateType

      eWSDateType

      Maps to CFDateRef.

      Available in OS X v10.2 and later.

    • eWSDataType

      eWSDataType

      Maps to CFDataRef.

      Available in OS X v10.2 and later.

    • eWSArrayType

      eWSArrayType

      Maps to CFArrayRef.

      Available in OS X v10.2 and later.

    • eWSDictionaryType

      eWSDictionaryType

      Maps to CFDictionaryRef.

      Available in OS X v10.2 and later.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.2 and later.

String Constants

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

    Declaration

    Objective-C

    CFStringRef kWSXMLRPCProtocol; CFStringRef kWSSOAP1999Protocol; CFStringRef kWSSOAP2001Protocol;

    Constants

    • kWSXMLRPCProtocol

      kWSXMLRPCProtocol

      XML-RPC protocol.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

    • kWSSOAP1999Protocol

      kWSSOAP1999Protocol

      SOAP v1.1 protocol.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

    • kWSSOAP2001Protocol

      kWSSOAP2001Protocol

      SOAP v1.2 protocol.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

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

    Constants

    • kWSMethodInvocationResult

      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.

    • kWSFaultString

      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.

    • kWSFaultCode

      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.

    • kWSFaultExtra

      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.

    • kWSNetworkStreamFaultString

      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.

    • kWSStreamErrorMessage

      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.

    • kWSStreamErrorDomain

      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.

    • kWSStreamErrorError

      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.

  • 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.

    Declaration

    Objective-C

    CFStringRef kWSHTTPMessage; CFStringRef kWSHTTPResponseMessage;

    Constants

    • kWSHTTPMessage

      kWSHTTPMessage

      The message.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

    • kWSHTTPResponseMessage

      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.

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

    Declaration

    Objective-C

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

    Constants

    • kWSHTTPVersion

      kWSHTTPVersion

      The CFHTTPMessageRef version such as “http/1.1”.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

    • kWSHTTPExtraHeaders

      kWSHTTPExtraHeaders

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

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

    • kWSHTTPProxy

      kWSHTTPProxy

      The CFURLRef of the SOCKS proxy.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

    • kWSHTTPFollowsRedirects

      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.

  • 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.

    Declaration

    Objective-C

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

    Constants

    • kWSDebugOutgoingHeaders

      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.

    • kWSDebugOutgoingBody

      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.

    • kWSDebugIncomingHeaders

      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.

    • kWSDebugIncomingBody

      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.

  • 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.

    Declaration

    Objective-C

    CFStringRef kWSSOAPMessageHeaders;

    Constants

    • kWSSOAPMessageHeaders

      kWSSOAPMessageHeaders

      A CFArrayRef of XML header elements, as CFStringRefs.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFStringRef kWSRecordParameterOrder; CFStringRef kWSRecordNamespaceURI; CFStringRef kWSRecordType;

    Constants

    • kWSRecordParameterOrder

      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.

    • kWSRecordNamespaceURI

      kWSRecordNamespaceURI

      A CFStringRef containing the namespace.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

    • kWSRecordType

      kWSRecordType

      A CFStringRef containing the record type.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

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

    Declaration

    Objective-C

    CFStringRef kWSMethodInvocationResultParameterName;

    Constants

    • kWSMethodInvocationResultParameterName

      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.

Result Codes

  • An internal framework error occured.

    Value

    -65793L

    Description

    An internal framework error occured.

    Available in OS X v10.2 and later.

  • A network error occured.

    Value

    -65794L

    Description

    A network error occured.

    Available in OS X v10.2 and later.

  • The server response was not valid XML.

    Value

    -65795L

    Description

    The server response was not valid XML.

    Available in OS X v10.2 and later.

  • The method invocation timed out.

    Value

    -65796L

    Description

    The method invocation timed out.

    Available in OS X v10.2 and later.

    • An internal framework error occured.

      Value

      -65793L

      Description

      An internal framework error occured.

      Available in OS X v10.2 and later.

    • A network error occured.

      Value

      -65794L

      Description

      A network error occured.

      Available in OS X v10.2 and later.

    • The server response was not valid XML.

      Value

      -65795L

      Description

      The server response was not valid XML.

      Available in OS X v10.2 and later.

    • The method invocation timed out.

      Value

      -65796L

      Description

      The method invocation timed out.

      Available in OS X v10.2 and later.