Skip Headers
Oracle® Database XML C API Reference
11g Release 2 (11.2)

Part Number E10770-02
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
CAXML01300

9 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."

Attachments are not allowed in Soap 1.1. In Soap 1.2, body may not have other elements if Fault is present.

The structure of a SOAP message is:

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

See Also:

CAXML6000

Package SOAP Interfaces

Table 9-1 summarizes the methods available through the SOAP package.

CAXML6001Table 9-1 Summary of SOAP Package Interfaces

Function Summary

XmlSoapAddBodyElement()

Adds an element to a SOAP message body.

XmlSoapAddFaultReason()

Adds additional Reason to Fault.

XmlSoapAddFaultSubDetail()

Adds additional child to Fault Detail.

XmlSoapAddHeaderElement()

Adds an element to a SOAP header.

XmlSoapCall()

Sends a SOAP message then waits for a reply.

XmlSoapCreateConnection()

Creates a SOAP connection object.

XmlSoapCreateCtx()

Creates and returns a SOAP context.

XmlSoapCreateMsg()

Creates and returns an empty SOAP message.

XmlSoapDestroyConnection()

Destroys a SOAP connection object.

XmlSoapDestroyCtx()

Destroys a SOAP context.

XmlSoapDestroyMsg()

Destroys a SOAP message created with XmlSoapCreateMsg.

XmlSoapError()

Gets a human readable error code.

XmlSoapGetBody()

Return a SOAP message's envelope body.

XmlSoapGetBodyElement()

Gets an element from a SOAP body.

XmlSoapGetEnvelope()

Returns a SOAP part's envelope.

XmlSoapGetFault()

Returns Fault code, reason, and details.

XmlSoapGetHeader()

Returns a SOAP message's envelope header.

XmlSoapGetHeaderElement()

Gets an element from a SOAP header.

XmlSoapGetMustUnderstand()

Gets mustUnderstand attribute from SOAP header element.

XmlSoapGetReasonLang()

Gets the language of a reason with the specified index.

XmlSoapGetReasonNum()

Determines the number of reasons in Fault element.

XmlSoapGetRelay()

Gets Relay attribute from SOAP header element.

XmlSoapGetRole()

Gets role from SOAP header element.

XmlSoapHasFault()

Determines if SOAP message contains Fault object.

XmlSoapSetFault()

Sets Fault in SOAP message.

XmlSoapSetMustUnderstand()

Sets mustUnderstand attribute for SOAP header element.

XmlSoapSetRelay()

Sets Relay attribute for a SOAP header element.

XmlSoapSetRole()

Sets role for SOAP header element.


CAXML6002

XmlSoapAddBodyElement()

Adds an element to a SOAP message body. Sets the numeric error code.

CAXML6003Syntax

xmlelemnode *XmlSoapAddBodyElement(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   oratext *qname,
   oratext *uri, 
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
qname
IN
QName of element to add
uri
IN
Namespace URI of element to add
xerr
IN/OUT
Error code

CAXML6004Returns

(xmlelemnode *) created element

CAXML6005

XmlSoapAddFaultReason()

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

CAXML6006Syntax

xmlerr XmlSoapAddFaultReason(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   ratext *reason,
    oratext *lang);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
reason
IN
Human-readable fault Reason
lang
IN
Language of reason

CAXML6007Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6008

XmlSoapAddFaultSubDetail()

Adds an additional child to Fault Detail. XmlSoapSetFault allows for creation of a Deatail element with only one child. Extra children could be added with this function.

CAXML6009Syntax

xmlerr XmlSoapAddFaultSubDetail(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   xmlelemnode *sub);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
sub
IN
subdetail tree

CAXML6010Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6011

XmlSoapAddHeaderElement()

Adds an element to a SOAP header.

CAXML6012Syntax

xmlelemnode *XmlSoapAddHeaderElement(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   oratext *qname,
   oratext *uri, 
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
qname
IN
QName of element to add
uri
IN
Namespace URI of element to add
xerr
IN/OUT
error code

CAXML6013Returns

(xmlelemnode *) created element

CAXML6014

XmlSoapCall()

Send a SOAP message over a connection and wait for the response; the message reply (an XML document) is parsed and returned as a SOAP message (equivalent to a DOM).

The message buffer is first used to serialize the outgoing message; if it's too small (overflow occurs), xerr gets XMLERR_SAVE_OVERFLOW and NULL is returned. The same buffer is then re-used to receive the replied SOAP message.

Opening the connection object is expected to cause an active SOAP handler to appear on the end-point; how this happens is up to the user. For HTTP, the URL should invoke a cgi-bin, or detect the application/soap+xml content-type.

CAXML6015Syntax

xmldocnode *XmlSoapCall(
   xmlsoapctx *ctx, 
   xmlsoapcon *con,
   xmldocnode *msg, 
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
con
IN
SOAP connection object
msg
IN
SOAP message to send
xerr
IN
numeric code of failure

CAXML6016Returns

(xmldocnode *) returned message, or NULL on failure with xerr set

CAXML6017

XmlSoapCreateConnection()

Create a SOAP connection object, specifying the binding (transport) and endpoint. The binding is an enum of type xmlsoapbind, and the endpoint depends on the binding.

Currently only HTTP binding is supported, and the endpoint is a URL. That URL should be active, i.e. a cgi-bin script or some mechanism to trigger SOAP message processing based on the Content-type of the incoming message ("application/soap+xml").

To control the HTTP access method (GET or POST), use the web-method property named XMLSOAP_PROP_WEB_METHOD which can have possible values XMLSOAP_WEB_METHOD_GET and XMLSOAP_WEB_METHOD_POST.

(conbuf, consiz) is the connection buffer used with LPU; for sending, it contains only the HTTP header, but on reception it holds the entire reply, including HTTP header and the full SOAP body. If no buffer is provided, one will be allocated for you. If size if zero, the default size (64K) will be used.

(msgbuf, msgsiz) is the message buffer used to form SOAP messages for sending. It needs to be large enough to contain the largest message which will be sent. If no buffer is specified, one will be allocated for you. If the size is zero, the default size (64K) will be used.

Two buffers are needed for sending since the SOAP message needs to be formed first in order to determine it's size; then, the HTTP header can be formed, since the Content-Length is now known.

CAXML6018Syntax

xmlsoapcon *XmlSoapCreateConnection(
   xmlsoapctx *ctx, 
   xmlerr *xerr,
   xmlsoapbind bind, 
   void *endp,
   oratext *conbuf, 
   ubig_ora consiz,
   oratext *msgbuf, 
   ubig_ora msgsiz, 
   ...);
Parameter In/Out Description
ctx
IN
SOAP context
xerr
OUT
numeric error code on failure
bind
IN
connection binding
endp
IN
connection endpoint
conbuf
IN/OUT
connection buffer (or NULL to have one allocated)
consiz
IN
size of connection buffer (or 0 for default size)
msgbuf
IN/OUT
message buffer (or NULL to have one allocated)
msgsiz
IN
size of message buffer (or 0 for default size)
...
IN
additional HTTP headers to set, followed by NULL

CAXML6019Returns

(xmlsoapcon *) connect object, or NULL on error with xerr set

CAXML6020

XmlSoapCreateCtx()

Creates and returns a SOAP context. This context must be passed to all XmlSoap APIs. Note the name provided should be unique and is used to identify the context when debugging. Options are specified as (name, value) pairs, ending with a NULL, same as for XmlCreate. If no options are desired, the NULL is still needed. Options are: debug_level (enables SOAP debug output to stderr), numeric level (the higher the level, the more detailed extensive the output), 0 for no debug (this is the default setting).

CAXML6021Syntax

xmlsoapctx *XmlSoapCreateCtx(
   xmlctx *xctx, 
   xmlerr *xerr, 
   oratext *name, 
   ...);
Parameter In/Out Description
xctx
IN
XML context
xerr
OUT
error return code on failure
name
IN
name of context; used for debugging
...
IN
options, as (name, value) pairs, followed by NULL

CAXML6022Returns

(xmlsoapctx *) SOAP context, or NULL on failure (w/xerr set)

CAXML6023

XmlSoapCreateMsg()

Creates and returns an empty SOAP message. The SOAP message will consist of an Envelope. The Envelope contains an empty Header and Body. A SOAP message is an XML document represented by a DOM, and is no different from any other XML document. All DOM operations are valid on the document, but be sure not to harm the overall structure. Changes should be restricted to creating and modifying elements inside the Header and Body.

CAXML6024Syntax

xmldocnode *XmlSoapCreateMsg(
   xmlsoapctx *ctx, 
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
xerr
OUT
error retrun code on failure

CAXML6025Returns

(xmldocnode *) SOAP message, or NULL on failure (w/xerr set)

CAXML6026

XmlSoapDestroyConnection()

Destroys a SOAP connection object made with XmlSoapCreateConnection and frees all allocated resources.

CAXML6027Syntax

xmlerr XmlSoapDestroyConnection(
   xmlsoapctx *ctx, 
   xmlsoapcon *con);
Parameter In/Out Description
ctx
IN
SOAP context
con
IN
SOAP connection

CAXML6028Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6029

XmlSoapDestroyCtx()

Destroys a SOAP context created with XmlSoapCreateCtx. All memory allocated will be freed, and all connections closed.

CAXML6030Syntax

xmlerr XmlSoapDestroyCtx(
   xmlsoapctx *ctx);
Parameter In/Out Description
ctx
IN
SOAP context

CAXML6031Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6032

XmlSoapDestroyMsg()

Destroys a SOAP message created with XmlSoapCreateMsg; this is the same as calling XmlFreeDocument.

CAXML6033Syntax

xmlerr XmlSoapDestroyMsg(
   xmlsoapctx *ctx,
   xmldocnode *msg);
Parameter In/Out Description
ctx
IN
SOAP connection
msg
IN
SOAP message

CAXML6034Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6035

XmlSoapError()

Retrives human readable representation of the error code. Optionally, retrieves the information about the error code of the underlying layer.

CAXML6036Syntax

oratext *XmlSoapError(
   xmlsoapctx *ctx, 
   xmlsoapcon *con,
   xmlerr err,
   uword *suberr,
   oratext **submsg);
Parameter In/Out Description
ctx
IN
SOAP context
con
IN
Connection about which additional info is requested
err
IN
Error code for which human readable information will be returned.
suberr
OUT
Error code from con
submsg
OUT
Human readable information about con error

CAXML6037Returns

(oratext *) error code

CAXML6038

XmlSoapGetBody()

Returns a SOAP message's envelope body.

CAXML6039Syntax

xmlelemnode *XmlSoapGetBody(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN
SOAP message
xmlerr
IN/OUT
error code

CAXML6040Returns

(xmlelemnode *) SOAP Body

CAXML6041

XmlSoapGetBodyElement()

Gets an element from a SOAP body.

CAXML6042Syntax

xmlelemnode *XmlSoapGetBodyElement(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   oratext *uri,
    oratext *local,
    xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN
SOAP message
uri
IN
Namespace URI of element to get
local
IN
Local name of element to get
xerr
IN/OUT
error code

CAXML6043Returns

(xmlelemnode *) named element, or NULL on error

CAXML6044

XmlSoapGetEnvelope()

Returns a SOAP part's envelope

CAXML6045Syntax

xmlelemnode *XmlSoapGetEnvelope(
   mlsoapctx *ctx, 
   xmldocnode *msg, 
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN
SOAP message
xerr
IN/OUT
error code

CAXML6046Returns

(xmlelemnode *) SOAP envelope

CAXML6047

XmlSoapGetFault()

Returns Fault code, reason, and details. Fetches the Fault information and returns through user variables. NULL may be supplied for any part which 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).

CAXML6048Syntax

xmlerr XmlSoapGetFault(
   xmlsoapctx *ctx, 
   xmldocnode *msg, 
   oratext **code,
   oratext **reason, 
   oratext **lang,
   oratext **node,
   oratext **role,
   xmlelemnode **detail);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
code
OUT
Code (1.2), faultcode (1.1)
reason
OUT
Human-readable fault Reason (1.2), faultreason (1.1)
lang
IN
Desired language for reason (1.2), not used ( NULL in 1.1)
node
OUT
Fault node
role
OUT
Role: next, none, or ulitmate receiver. Not used in 1.1
detail
OUT
User-defined details

CAXML6049Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6050

XmlSoapGetHeader()

Returns a SOAP message's envelope header.

CAXML6051Syntax

xmlelemnode *XmlSoapGetHeader(
   xmlsoapctx *ctx, 
  xmldocnode *msg, 
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN
SOAP message
xerr
IN/OUT
error code

CAXML6052Returns

(xmlelemnode *) SOAP header

See Also:

XmlSoapGetBody()
CAXML6053

XmlSoapGetHeaderElement()

Gets an element from a SOAP header. Sets a numeric error code.

CAXML6054Syntax

xmlelemnode *XmlSoapGetHeaderElement(
   xmlsoapctx *ctx,
   xmldocnode *msg,
   oratext *uri,
   oratext *local,
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN
SOAP message
uri
IN
Namespace URI of element to get
local
IN
Local name of element to get
xerr
IN/OUT
Error code

CAXML6055Returns

(xmlelemnode *) named element, or NULL on error

CAXML6056

XmlSoapGetMustUnderstand()

Gets mustUnderstand attribute from SOAP header element. The absence of this attribute is not an error and treated as value FALSE. To indicate the absence of an attribute, the error code XMLERR_SOAP_NO_MUST_UNDERSTAND is returned in this case, XMLERR_OK (0) is returned if the attribute is present. Other appropriate error codes might be returned. User supplied mustUnderstand value is set accordingly.

CAXML6057Syntax

xmlerr XmlSoapGetMustUnderstand(
   xmlsoapctx *ctx, 
   xmlelemnode *elem,
   boolean *mustUnderstand);
Parameter In/Out Description
ctx
IN
SOAP context
elem
IN
SOAP header element
mustUnderstand
OUT
mustUnderstand value, TRUE|FALSE

CAXML6058Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6059

XmlSoapGetReasonLang()

Gets the language of a reason with a particular index.

CAXML6060Syntax

xmlerr XmlSoapGetReasonLang(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   ub4 index, 
   oratext **lang);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN
SOAP message
indx
IN
Index of fault reason
lang
IN
Reason language

CAXML6061Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6062

XmlSoapGetReasonNum()

Determines the number of reasons in Fault element. Returns 0 if Fault is not present.

CAXML6063Syntax

ub4 XmlSoapGetReasonNum(
   xmlsoapctx *ctx, 
   xmldocnode *msg);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN
SOAP message

CAXML6064Returns

(ub4 *) #num reasons

CAXML6065

XmlSoapGetRelay()

Gets Relay attribute from SOAP header element.

CAXML6066Syntax

xmlerr XmlSoapGetRelay(
   xmlsoapctx *ctx, 
   xmlelemnode *elem,
   boolean *Relay);
Parameter In/Out Description
ctx
IN
SOAP context
elem
IN
SOAP header element
Relay
OUT
Relay value

CAXML6067Returns

xmlerr numeric error code, XMLERR_OK on success

CAXML6068

XmlSoapGetRole()

Gets role from SOAP header element. If the element has no role, XMLERR_SOAP_NO_ROLE is returned, otherwise XMLERR_OK (0) is returned and the user's role is set accordingly. if the element has no role, then according to the standard, the user's role is set to XMLSOAP_ROLE_ULT.

CAXML6069Syntax

xmlerr XmlSoapGetRole(
   xmlsoapctx *ctx, 
   xmlelemnode *elem, 
   xmlsoaprole *role);
Parameter In/Out Description
ctx
IN
SOAP context
elem
IN
SOAP header element
role
OUT
Role value

CAXML6070Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6071

XmlSoapHasFault()

Determines if SOAP message contains Fault object.

CAXML6072Syntax

boolean XmlSoapHasFault(
   xmlsoapctx *ctx, 
   xmldocnode *msg, 
   xmlerr *xerr);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN
SOAP message
xerr
IN/OUT
Error code

CAXML6073Returns

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

CAXML6074

XmlSoapSetFault()

Sets Fault in SOAP message.

CAXML6075Syntax

xmlerr XmlSoapSetFault(
   xmlsoapctx *ctx, 
   xmldocnode *msg,
   oratext *node, 
   oratext *code, 
   oratext *reason, 
   oratext *lang, 
   oratext *role, 
   xmlelemnode *detail);
Parameter In/Out Description
ctx
IN
SOAP context
msg
IN/OUT
SOAP message
node
IN
URI of SOAP node which faulted, Node (1.2), faultactor(1.1)
code
IN
Code (1.2), faultcode (1.1)
reason
IN
Human-readable fault Reason (1.2), faultreason (1.1)
lang
IN
Language of reason (1.2), unused (1.1)
role
IN
URI representing role, Role (1.2), unused (1.1)
detail
IN
detail elements (user-defined)

CAXML6076Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6077

XmlSoapSetMustUnderstand()

Sets mustUnderstand attribute for SOAP header element. According to the standard, if the value is FALSE, the attribute is not set.

CAXML6078Syntax

xmlerr XmlSoapSetMustUnderstand(
   xmlsoapctx *ctx, 
   xmlelemnode *elem,
   boolean mustUnderstand);
Parameter In/Out Description
ctx
IN
SOAP context
elem
IN/OUT
SOAP header element
mustUnderstand
IN
mustUnderstand value, TRUE|FALSE

CAXML6079Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

See Also:

XmlSoapSetRole()
CAXML6080

XmlSoapSetRelay()

Sets Relay attribute for a SOAP header element. If the value is FALSE, the attribute is not set.

CAXML6081Syntax

xmlerr XmlSoapSetRelay(
   xmlsoapctx *ctx,
   xmlelemnode *elem,   boolean Relay);
Parameter In/Out Description
ctx
IN
SOAP context
elem
IN/OUT
SOAP header element
Relay
IN
Relay; TRUE|FALSE

CAXML6082Returns

(xmlerr) numeric error code, XMLERR_OK [0] on success

CAXML6083

XmlSoapSetRole()

Sets role for SOAP header element. If the role specified is XMLSOAP_ROLE_ULT, then according to the standard the attribute is not set.

CAXML6084Syntax

xmlerr XmlSoapSetRole(
   xmlsoapctx *ctx, 
   xmlelemnode *elem, 
   xmlsoaprole role);
Parameter In/Out Description
ctx
IN
SOAP context
elem
IN/OUT
SOAP header element
role
IN
Role value

CAXML6085Returns

xmlerr numeric error code, XMLERR_OK on success

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.

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

  • Package SOAP Interfaces
    • XmlSoapAddBodyElement()
    • XmlSoapAddFaultReason()
    • XmlSoapAddFaultSubDetail()
    • XmlSoapAddHeaderElement()
    • XmlSoapCall()
    • XmlSoapCreateConnection()
    • XmlSoapCreateCtx()
    • XmlSoapCreateMsg()
    • XmlSoapDestroyConnection()
    • XmlSoapDestroyCtx()
    • XmlSoapDestroyMsg()
    • XmlSoapError()
    • XmlSoapGetBody()
    • XmlSoapGetBodyElement()
    • XmlSoapGetEnvelope()
    • XmlSoapGetFault()
    • XmlSoapGetHeader()
    • XmlSoapGetHeaderElement()
    • XmlSoapGetMustUnderstand()
    • XmlSoapGetReasonLang()
    • XmlSoapGetReasonNum()
    • XmlSoapGetRelay()
    • XmlSoapGetRole()
    • XmlSoapHasFault()
    • XmlSoapSetFault()
    • XmlSoapSetMustUnderstand()
    • XmlSoapSetRelay()
    • XmlSoapSetRole()

This Document

New and changed documents:
RSS Feed HTML RSS Feed PDF