../E10771-01.epub /> ../E10771-01.mobi />

6 Package SOAP APIs for C++

W3C: "SOAP is a lightweight protocol for exchange of information in a decentralized, distributed environment. It is an XML based protocol that consists of three parts: an envelope that defines a framework for describing what is in a message and how to process it, a set of encoding rules for expressing instances of application-defined datatypes, and a convention for representing remote procedure calls and responses."

The structure of a SOAP message is:

[SOAP message (XML document)
   [SOAP envelope
      [SOAP header?
            element*
      ]
      [SOAP body
           (element* | Fault)?
      ]
   ]
]

This chapter contains the following sections:


SOAP Datatypes

Table 6-1 summarizes the datatypes of the SOAP package.

Table 6-1 Summary of Datatypes; SOAP Package

Datatype Description

SoapExceptionCode

Defines Soap-related exception codes.

SoapBinding

Defines binding for SOAP connections.

SoapRole

Defines roles for SOAP nodes.



SoapExceptionCode

Defines Soap-related exception codes.

typedef enum SoapExceptionCode {
   SOAP_UNDEFINED_ERR       = 0,
   SOAP_OTHER_ERR           = 1} SoapExceptionCode;

SoapBinding

Defines binding for SOAP connections. HTTP is currently the only choice.

typedef enum SoapBinding {
   BIND_NONE  = 0,  /* none */
   BIND_HTTP  = 1   /* HTTP */ } SoapBinding;

SoapRole

Defines roles for SOAP nodes.

typedef enum SoapRole {
   ROLE_UNSET = 0,  /* not specified */
   ROLE_NONE  = 1,  /* "none" */
   ROLE_NEXT  = 2,  /* "next" */
   ROLE_ULT   = 3   /* "ultimateReceiver" */ } SoapRole;

SoapException Interface

Table 6-2 summarizes the methods available through the SoapException Interface.

Table 6-2 Summary of SoapException Interfaces

Datatype Description

getCode()

Get Oracle XML error code embedded in the exception

getMessage()

Get Oracle XML error message.

getMesLang()

Get current language encoding of error messages.

getSoapCode()

Get Soap exception code embedded in the exception.



getCode()

Get Oracle XML error code embedded in the exception. This is a virtual member function inherited from XMLException.

Syntax

virtual unsigned getCode() const = 0;

Returns

(unsigned) numeric error code (0 on success)


getMessage()

Get Oracle XML error message. Virtual member function inherited from XMLException.

Syntax

virtual oratext* getMessage() const = 0;

Returns

(oratext *) Error message


getMesLang()

Get current language encoding of error messages. Virtual member function inherited from XMLException.

Syntax

virtual oratext* getMesLang() const = 0;

Returns

(oratext*) Current language (encoding) of error messages


getSoapCode()

Get SOAP exception code embedded in the exception. This is a virtual member function that defines a prototype for implementing defined member functions that return SOAP API exception codes.

Syntax

virtual SoapExceptionCode getSoapCode() const = 0;

Returns

(SoapExceptionCode) exception code


ConnectRef Interface

Table 6-3 summarizes the methods available ConnectRef Interface.

Table 6-3 Summary of ConnectRef Interfaces

Datatype Description

~ConnectRef()

Destroys a SOAP connection object

call()

Send a SOAP message then waits for a response.



~ConnectRef()

Destructor. Destroys a SOAP connection object and frees any resources associated with it.

Syntax

~ConnectRef() throw (SoapException);

call()

Send a SOAP message then waits for a response.

Syntax

DocumentRef< Node>* call( 
   DocumentRef< Node>& msg) throw (SoapException);
Parameter Description
msg
The SOAP message that is sent.

Returns

(DocumentRef) returned message


MsgFactory Interface

Table 6-4 summarizes the methods available through the MsgFactory Interface.

Table 6-4 Summary of MsgFactory Interfaces

Datatype Description

~MsgFactory()

Destroys the SOAP message factory instance.

MsgFactory()

Creates and returns a SOAP Message Factory instance.

addBodyElement()

Adds an element to a SOAP message body.

addFaultReason()

Add s an additional Reason to Fault

addHeaderElement()

Adds an element to SOAP header.

createConnection()

Creates a SOAP connection.

createMessage()

Creates and returns an empty SOAP message.

destroyMessage()

Destroyw a SOAP message.

getBody()

Returns a SOAP message's envelope body..

getBodyElement()

Gets an element from a SOAP body.

getEnvelope()

Returns a SOAP part's envelope.

getFault()

Returns Fault code, reason, and details.

getHeader()

Returns a SOAP message's envelope header..

getHeaderElement()

Gets an element from a SOAP header.

getMustUnderstand()

Gets mustUnderstand attribute from the SOAP header element.

getReasonNum()

Gets the number of reasons in Fault element.

getReasonLang()

Gets a language of a reason with a particular index.

getRole()

Gets role from SOAP header element.

hasFault()

Determines if a SOAP message contains a Fault object.

setFault()

Sets Fault in a SOAP message.

setMustUnderstand()

Sets mustUnderstand attribute for the SOAP header element.

setRole()

Sets the role for SOAP header element.



~MsgFactory()

Destructor. Destroys the SOAP message factory. All allocated memory is frieed and all connections are closed.

Syntax

~MsgFactory() throw (SoapException);

MsgFactory()

Creates and returns a SOAP Message Factory instance.

Syntax

MsgFactory( 
   Context* ctx_ptr) throw (SoapException);
Parameter Description
ctx_ptr
TContext object

Returns

(MsgFactory) object


addBodyElement()

Adds an element to a SOAP message body.

Syntax

Node* addBodyElement( DocumentRef< Node>& msg,
   oratext *qname,
   oratext *uri) throw (SoapException);
Parameter Description
msg
SOAP message
qname
QName of element to add
uri
Namespace URI of element to add

Returns

(Node*) pointer to the created element


addFaultReason()

Adds an additional Reason to Fault. The same re son text may be provided in different languages. When the fault is created, the primary language and reasonare added at that time; use this function to add additional translations of the reason.

Syntax

void addFaultReason( 
   DocumentRef< Node>& msg,
   oratext *reason, 
   oratext *lang) throw (SoapException);
Parameter Description
msg
SOAP message
reason
Human-readable fault reason
lang
Language of reason


addHeaderElement()

Adds an element to SOAP header.

Syntax

Node* addHeaderElement( 
   DocumentRef< Node>& msg,
   oratext *qname, oratext *uri) throw (SoapException);
Parameter Description
msg
SOAP message
qname
QName of element to add
uri
Namespace URI of element to add

Returns

(Node*) pointer to the created element


createConnection()

Creates a SOAP connection object. The connection reference object should explicitly deleted by the user.

Syntax

ConnectRef< Node>* createConnection(
   SoapBinding bind,
   void *endp,
   oratext *buf,
   ubig_ora bufsiz,
   oratext *msgbuf,
   ubig_ora msgbufsiz) throw (SoapException);
Parameter Description
bind
connection binding
endp
connection endpoint
buf
data buffer (or NULL to have one allocated)
bufsiz
size of data buffer (or 0 for default size)
msgbuf
message buffer (or NULL to have one allocated)
msgfubsiz
size of message buffer (or 0 for default size)

Returns

(ConnectRef) connect object


createMessage()

Creates and returns an empty SOAP message. The reference object should be explicitly deleted by the user when no longer needed.

Syntax

DocumentRef< Node>* CreateMessage() throw (SoapException);

Returns

(DocumentRef*) SOAP message, or an exception


destroyMessage()

Destroys a SOAP message.

Syntax

void destroyMessage(
   DocumentRef< Node>& msg) throw (SoapException);
Parameter Description
msg
The SOAP message.


getBody()

Returns a SOAP message's envelope body as a pointer to the body's element node.

Syntax

Node* getBody( 
   DocumentRef<Node>& msg) throw (SoapException);
Parameter Description
msg
SOAP message

Returns

(Node*) pointer to the SOAP message's envelope body


getBodyElement()

Gets an element from a SOAP body as a pointer to its element node.

Syntax

Node* getBodyElement(
   DocumentRef< Node>& msg,
   oratext *uri,
   oratext *local) throw (SoapException);
Parameter Description
msg
SOAP message
uri
Namespace URI of element to add
local
Local name of element to get

Returns

(Node*) pointer to the named element


getEnvelope()

Returns a SOAP part's envelope as a pointer to envelope element node.

Syntax

Node* getEnvelope( 
   DocumentRef<Node>& msg) throw (SoapException);
Parameter Description
msg
SOAP message

Returns

(Node*) pointer to the SOAP message's envelope


getFault()

Returns Fault code, reason, and details through user variables. NULL may be supplied for any part that is not needed. For lang, if the pointed-to variable is NULL, it will be set to the default language, that of the first reason.

Syntax

Node* getFault( 
   DocumentRef< Node>& msg,
   oratext **code,
   oratext **reason,
   oratext **lang,
   oratext **node,
   oratext **role) throw (SoapException);
Parameter Description
msg
SOAP message
code
Fault code
reason
Human-readable fault reason
lang
Desired reason language or NULL (default language, same as for the first reason)
node
Fault node
role
Role: next, none, or ulitmate receiver (not used in 1.1)

Returns

(Node) pointer to the detail


getHeader()

Returns a SOAP message's envelope header as a pointer to the header element node.

Syntax

Node* getHeader( 
   DocumentRef< Node>& msg) throw (SoapException);
Parameter Description
msg
SOAP message

Returns

(Node*) pointer to the SOAP message's envelope header


getHeaderElement()

Gets an element from a SOAP header as a pointer to its element node.

Syntax

Node* getHeaderElement( 
   DocumentRef< Node>& msg,
   oratext *uri, 
   oratext *local) throw (SoapException);
Parameter Description
msg
SOAP message
uri
Namespace URI of element to get
local
Local name of element to get

Returns

(Node*) pointer to the named element


getMustUnderstand()

Gets mustUnderstand attribute from SOAP header element.

Syntax

boolean getMustUnderstand( 
   ElementRef< Node>& elem) throw (SoapException);
Parameter Description
elem
SOAP header element

Returns

(boolean) value of the mustUnderstand attribute


getReasonNum()

Determines the number of reasons in the Fault element. Returns 0 if no Fault.

Syntax

ub4 getReasonNum(
   DocumentRef< Node>& msg) throw (SoapException);
Parameter Description
msg
SOAP message

Returns

(up4) number of reasons in Fault element


getReasonLang()

Returns the language of a reason with a particular index.

Syntax

oratext* getReasonLang( 
   DocumentRef< Node>& msg,
   ub4 idx) throw (SoapException);
Parameter Description
msg
SOAP message
idx
index of a fault reason

Returns

(oratext *) value of property or NULL.


getRole()

Gets role from SOAP header element.

Syntax

SoapRole getRole( 
   ElementRef< Node>& elem) throw (SoapException);
Parameter Description
elem
Reference to the header element

Returns

(SoapRole) header element's role


hasFault()

Determines if a SOAP message contains a Fault object.

Syntax

boolean hasFault( 
   DocumentRef< Node>& msg) throw (SoapException);
Parameter Description
msg
SOAP message

Returns

(boolean) TRUE if there's a Fault, FALSE if not


setFault()

Sets Fault in a SOAP message.

Syntax

void setFault(
   DocumentRef< Node>& msg,
   oratext *node,
   oratext *code, 
   oratext *reason,
   oratext *lang,
   oratext *role,
  ElementRef< Node>& detail) throw (SoapException);
Parameter Description
msg
SOAP message
node
URI of SOAP node which faulted
code
Fault code
reason
Human-readable fault reason
lang
Language
role
URI representing role, Role (1.2), unused (1.1)
detail
User-defined elements


setMustUnderstand()

Sets mustUnderstand attribute for the SOAP header element.

Syntax

void setMustUnderstand( 
   ElementRef< Node>& elem,
   boolean mustUnderstand) throw (SoapException);
Parameter Description
elem
SOAP header element
mustUnderstand
mustUnderstand value (TRUE or FALSE)


setRole()

Sets the role for SOAP header element.

Syntax

void setRole( 
   ElementRef< Node>& elem, 
   SoapRole role) throw (SoapException);
Parameter Description
elem
reference to the header element
role
role value