Skip Headers
Oracle® Database XML C++ API Reference
10g Release 2 (10.2)
Part Number B16206-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Master Index
Master Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
PDF · Mobi · ePub

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:

See Also:

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 of 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 of 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 of 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

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Master Index
Master Index		 Go to Feedback page
Contact Us