Skip Headers
Oracle® Database XML C++ API Reference
11g Release 2 (11.2)
Part Number E10771-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
CPXML02100

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:

CPXML02105

SOAP Datatypes

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

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

CPXML2870

SoapExceptionCode

Defines Soap-related exception codes.

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

SoapBinding

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

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

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;
CPXML02110

SoapException Interface

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

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

CPXML2874

getCode()

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

CPXML2875Syntax

virtual unsigned getCode() const = 0;

CPXML2876Returns

(unsigned) numeric error code (0 on success)

CPXML2877

getMessage()

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

CPXML2878Syntax

virtual oratext* getMessage() const = 0;

CPXML2879Returns

(oratext *) Error message

CPXML2880

getMesLang()

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

CPXML2881Syntax

virtual oratext* getMesLang() const = 0;

CPXML2882Returns

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

CPXML2883

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.

CPXML2884Syntax

virtual SoapExceptionCode getSoapCode() const = 0;

CPXML2885Returns

(SoapExceptionCode) exception code

CPXML02120

ConnectRef Interface

Table 6-3 summarizes the methods available ConnectRef Interface.

CPXML2886Table 6-3 Summary of ConnectRef Interfaces

Datatype Description

~ConnectRef()

Destroys a SOAP connection object

call()

Send a SOAP message then waits for a response.

CPXML2887

~ConnectRef()

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

CPXML2888Syntax

~ConnectRef() throw (SoapException);
CPXML2889

call()

Send a SOAP message then waits for a response.

CPXML2890Syntax

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

CPXML2891Returns

(DocumentRef) returned message

CPXML02130

MsgFactory Interface

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

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

CPXML2893

~MsgFactory()

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

CPXML2894Syntax

~MsgFactory() throw (SoapException);
CPXML2895

MsgFactory()

Creates and returns a SOAP Message Factory instance.

CPXML2896Syntax

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

CPXML2897Returns

(MsgFactory) object

CPXML2898

addBodyElement()

Adds an element to a SOAP message body.

CPXML2899Syntax

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

CPXML2900Returns

(Node*) pointer to the created element

CPXML2901

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.

CPXML2902Syntax

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

CPXML2903

addHeaderElement()

Adds an element to SOAP header.

CPXML2904Syntax

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

CPXML2905Returns

(Node*) pointer to the created element

CPXML2906

createConnection()

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

CPXML2907Syntax

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)

CPXML2908Returns

(ConnectRef) connect object

CPXML2909

createMessage()

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

CPXML2910Syntax

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

CPXML2911Returns

(DocumentRef*) SOAP message, or an exception

CPXML2912

destroyMessage()

Destroys a SOAP message.

CPXML2913Syntax

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

CPXML2914

getBody()

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

CPXML2915Syntax

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

CPXML2916Returns

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

CPXML2917

getBodyElement()

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

CPXML2918Syntax

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

CPXML2919Returns

(Node*) pointer to the named element

CPXML2920

getEnvelope()

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

CPXML2921Syntax

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

CPXML2922Returns

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

CPXML2923

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.

CPXML2924Syntax

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)

CPXML2925Returns

(Node) pointer to the detail

CPXML2926

getHeader()

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

CPXML2927Syntax

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

CPXML2928Returns

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

CPXML2929

getHeaderElement()

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

CPXML2930Syntax

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

CPXML2931Returns

(Node*) pointer to the named element

CPXML2932

getMustUnderstand()

Gets mustUnderstand attribute from SOAP header element.

CPXML2933Syntax

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

CPXML2934Returns

(boolean) value of the mustUnderstand attribute

CPXML2935

getReasonNum()

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

CPXML2936Syntax

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

CPXML2937Returns

(up4) number of reasons in Fault element

CPXML2938

getReasonLang()

Returns the language of a reason with a particular index.

CPXML2939Syntax

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

CPXML2940Returns

(oratext *) value of property or NULL.

CPXML2941

getRole()

Gets role from SOAP header element.

CPXML2942Syntax

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

CPXML2943Returns

(SoapRole) header element's role

CPXML2944

hasFault()

Determines if a SOAP message contains a Fault object.

CPXML2945Syntax

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

CPXML2946Returns

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

CPXML2947

setFault()

Sets Fault in a SOAP message.

CPXML2948Syntax

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

CPXML2949

setMustUnderstand()

Sets mustUnderstand attribute for the SOAP header element.

CPXML2950Syntax

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

CPXML2951

setRole()

Sets the role for SOAP header element.

CPXML2952Syntax

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

Reader Comment

   

Comments, corrections, and suggestions are forwarded to authors every week. By submitting, you confirm you agree to the terms and conditions. Use the OTN forums for product questions. For support or consulting, file a service request through My Oracle Support.

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
Hide Navigation

Quick Lookup

Database Library · Master Index · Master Glossary · Book List · Data Dictionary · SQL Keywords · Initialization Parameters · Advanced Search · Error Messages

Main Categories

This Page

  • SOAP Datatypes
    • SoapExceptionCode
    • SoapBinding
    • SoapRole
  • SoapException Interface
    • getCode()
    • getMessage()
    • getMesLang()
    • getSoapCode()
  • ConnectRef Interface
    • ~ConnectRef()
    • call()
  • MsgFactory Interface
    • ~MsgFactory()
    • MsgFactory()
    • addBodyElement()
    • addFaultReason()
    • addHeaderElement()
    • createConnection()
    • createMessage()
    • destroyMessage()
    • getBody()
    • getBodyElement()
    • getEnvelope()
    • getFault()
    • getHeader()
    • getHeaderElement()
    • getMustUnderstand()
    • getReasonNum()
    • getReasonLang()
    • getRole()
    • hasFault()
    • setFault()
    • setMustUnderstand()
    • setRole()

This Document

New and changed documents:
RSS Feed HTML RSS Feed PDF