Home > Articles > Programming > Windows Programming

  • Print
  • + Share This

The SOAP Header

Because the SOAP Header is an optional object, you might or might not find header information serialized in a given SOAP packet. But if there is header information, all of that information must be serialized within the SOAP Header object, which must be the first (XML) child of the Envelope element. That's where you'll find it, but what is it used for?

Well, in a nutshell, the SOAP Header is used to transmit auxiliary information relevant to the Web Service processing that isn't part of the method signature. For example, imagine that you have a Web Service that specifies the toppings and crust style of the pizza that you intend to order (in C#):

OrderInfo OrderPizza(int[] toppings, int[] crust, PaymentInfo pi);

For this example, assume that the OrderInfo structure contains delivery information such as order confirmation, delivery timeline, and so on. The integer arrays contain integers that enumerate the various toppings and crusts available to you. The payment information structure contains payment data, such as a credit card number.

The Web Service, in this case, accepts your pizza order (presumably, you called another Web Service before this to establish your identity and delivery information). But it isn't a stretch to believe that there should be some sort of encryption associated with this invocation. That is, as the customer, you probably want to see at least the payment information, if not the entire packet, encrypted.

The fact that the payment information is encrypted could be verified using the encodingStyle attribute, but an alternate (and probably better) design might be to include public key information necessary to decrypt the payment data as SOAP Header information. This is the strategy used by the SOAP Digital Signatures specification, found at http://www.w3.org/TR/SOAP-dsig/ (we won't go into SOAP digital signature processing here—it's important to see only that the cypher information is transmitted within the SOAP Header at this point). What the pizza chef is interested in knowing is that you placed an order. What the pizza-ordering software is concerned with is the integrity of the payment information, which is orthogonal to the method signature. That is, decryption keys are (obviously) important to the processing of the pizza order, but the cypher information isn't actually necessary to make the pizza from a toppings and crust perspective.

The arrangement and contents of the header are specific to the Web Service. If the information is well-formed XML and otherwise adheres to the SOAP specification, you can put anything in there that you want using any XML vocabulary that you want. Anyone who wants to insert Header information may do so, but you'll all use the single SOAP Header XML element. As a result, each child element within the Header must be qualified using a namespace. After all, you have to be able to pull the header information back out again; to do that reliably, you'll need the associated namespace. One example of a very complex SOAP Header can be found in the SOAP Digital Signature specification. Luckily, most header entries are not this complex. Other simpler examples might include these:

  • Transaction IDs

  • Packet sequence values

  • Causality IDs (deadlock prevention)

  • Authentication information

  • Session identification information

  • Message routing information

  • Other Web Service method metadata

This isn't an exhaustive list, to be sure, but it hopefully gives you an idea of the types of things that SOAP headers typically convey.

According to the SOAP specification, one rule to follow, though, is to keep the header information self-contained. That is, the XML in the header should not somehow refer to the SOAP Body. This allows SOAP processing software to analyze and deal with header information without necessarily processing the body. In practice, this rule is sometimes broken to allow for more generic services. For example, a notable exception to this rule is provided by the SOAP Digital Signature specification. But there is a clear need to indicate body contents if you're encrypting a portion of the body using public key information found in the header. For all intents and purposes, the header elements should be self-contained, at least within the header element.

SOAP Header Attributes

As with the SOAP Envelope, the SOAP Header has attributes that you apply to indicate that certain behavior is desired or required. For example, it doesn't make sense for a Web Service to process encrypted SOAP Body information if it cannot decipher the encryption algorithm or digital key. You might see two predefined SOAP Header element attributes and another attribute applied to Header elements from time to time.

The Header mustUnderstand Attribute

The SOAP Header attribute that you see used most often is soap:mustUnderstand, and its intent and use is probably relatively obvious. If you apply this attribute to a given SOAP Header element, the recipient is bound, according to the SOAP specification, to return a fault packet if it does not actually understand the Header information:

soap:mustUnderstand="true"

Note that the SOAP 1.1 specification tells you to use values of 0 and 1, but the W3 Schema specification has subsequently been updated, so Boolean values for true and false are now also potentially serialized as the strings "true" and "false". Either value should be respected by the receiver, although there is no universal guarantee this will be the case.

You don't need to provide the attribute if the header information is optional. That is, if you intend to use a mustUnderstand value of false, you alternatively could have not included the attribute at all. The default condition for SOAP Header elements is that mustUnderstand is false.

The Header actor Attribute

As it happens, SOAP is actually quite expressive with respect to the varieties of XML serializations that you can use to express similar things. Because of this, SOAP is good for many more tasks than just RPC. In fact, when it's used for RPC purposes, SOAP constrains the packet serialization rather tightly. When it's used for general-purpose data transmission, such as for messaging, SOAP is much more flexible.

One of the things that messaging systems are interested in achieving is transmission of a message from stop to stop, with each stop adding or removing pieces of the message as it travels from source to destination. These stops have a more formal name: actor. You will also find actors that are not the ultimate recipient of the SOAP message referred to as intermediaries, but they are not referenced as such in the SOAP specification itself.

The contents of the message, contained within the SOAP Body, are typically directed to a particular actor. Intermediate processing can and does take place usually through modifications to the SOAP Header. As the SOAP packet moves from actor to actor, each actor reviews the SOAP Header and twiddles the bits as necessary. What the actors do with the header information and how many actors are involved is entirely up to the designers of the particular Web Service.

One thing that the actors must do, however, is adjust the actor attribute as the SOAP packet moves from stop to stop. The actor attribute's value is actually the URI of the next stop in the message path. There is a special URI for "next":

http://schemas.xmlsoap.org/soap/actor/next

At a minimum, each actor is required to strip its own URI from the actor attribute and replace the attribute value with the URL of the next actor, or with the special "next" destination URI, if that is more appropriate. What "next" specifically means is that this header is intended for the recipient of the message. Any additional header child elements messages may be reviewed based on URI. Any header child elements intended for the recipient must be removed by the recipient from the Header before processing continues. The Header child elements represent a contract between the entity that last held the message and the current recipient.

The concept of an actor isn't typically associated with RPC-style communications. With RPC, you're usually more interested in sending information to a specific endpoint. Messages, on the other hand, often bounce around the Internet until they wind their way to their ultimate destination—at least, the potential for this style of communication is possible. This is actually the purpose of the SOAP Routing Protocol (see http://www.gotdotnet.com/team/xml_wsspecs/soap-rp/default.html) and beyond the scope of this chapter.

The SOAP root Attribute

If you've read the SOAP specification regarding the SOAP root attribute and wondered what it means by "object serialization graph," you're not alone! This attribute can actually be applied to elements in either the SOAP Header or the Body, and very often what it means depends upon where you find it.

If you serialized a linked list within the SOAP Body as a method parameter, that linked list would have a head node. As you serialize the list, you march through the nodes of the list, converting their in-memory representation to XML. One mechanism that you can use to indicate which list node was actually the first is to apply the SOAP root attribute to that XML element:

soapenc:root="true"

Again, the SOAP specification refers to using values of 0 and 1, but the W3 XML Schema specification has been updated since the publication of the SOAP specification, so "true" and "false" are also appropriate. The SOAP processing software on the receiving end can then scan the XML for this attribute and begin deserialization proceedings with that element.

Applying the root attribute to the head node of a linked list is relatively intuitive. But the root attribute has another purpose. The SOAP Header element can possibly have one or more child XML elements. If you serialize many (related) Header child elements, from an XML perspective, they all appear at the same level within the document—children of the Header element. Yet it is conceivable that not all the Header elements have equal importance. So there is a potential conflict, depending upon how you serialize Header elements: You would normally assume that XML elements at the same level would be of equal importance, yet, from a SOAP Header perspective, this might not be the case. If this is so—and this depends entirely on what you intend to serialize—you have the option of inserting the SOAP root attribute to one or more of the Header element's child elements to promote its importance. The attribute simply provides a mechanism to make one or more elements stand out from the rest.

The SOAP Header is somewhat free-form. You can shove nearly anything in the Header itself and rest assured that you've followed the SOAP specification. The SOAP Body, however, can be a bit more constrained if you're not using WSDL document/literal encoding. It's also where the actual packet payload is recorded, so it's a critical SOAP object. Let's see how the SOAP Body is constructed.

  • + Share This
  • 🔖 Save To Your Account

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020