---

Web Services Core Foundation CallBacks

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.

• WSClientContextRetainCallBackProcPtr
• WSClientContextReleaseCallBackProcPtr
• WSClientContextCopyDescriptionCallBackProcPtr

Method Invocation Callbacks

• WSMethodInvocationCallBackProcPtr
• WSMethodInvocationSerializationProcPtr
• WSMethodInvocationDeserializationProcPtr

Protocol Handler Callbacks

• WSProtocolHandlerSerializationProcPtr
• WSProtocolHandlerDeserializationProcPtr

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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac 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 Mac OS X v10.3 and later.

Declared In

WSProtocolHandler.h

---