PATH  Documentation > WebObjects 4.5 > WebObjects Reference

Table of Contents

WOMessage


Inherits from: NSObject
Conforms to: NSObject
(NSObject)
Declared in: WebObjects/WOMessage.h



Class Description

WOMessage is the parent class for both WORequest and WOResponse,and implements much of the behavior that is generic to both. WOMessage represents a message with an HTTP header and either HTML or XML content. HTML content is typically used when interacting with a Web browser, while XML content can be used in messages that originate from or are destined for another application (either an application that "speaks" XML or another WebObjects application).

The methods of the WOMessage class can be divided primarily into two groups, those that deal with a message's content and those that read and set header information. Most of the remaining WOMessage methods control how the content is encoded and allow you to attach arbitrary "user info" to your WOMessage objects in order to pass information about a given message to other objects within your application.




Content Encodings

You can set the string encoding used for the response content with setContentEncoding: and you find out what the current encoding is with contentEncoding. An integer represents the type of encoding. The following table lists these integer values along with their WebObjects string-constant names.


Headers are case-insensitive. WebObjects enforces the HTTP specification, but avoid mixing the case of header keys. See the HTTP specification or HTTP documentation for more information on the HTTP headers and version.
int Value WebObjects Name Notes
1 NSASCIIStringEncoding 0 through 127
2 NSNEXTSTEPStringEncoding  
3 NSJapaneseEUCStringEncoding  
4 NSUTF8StringEncoding  
5 NSISOLatin1StringEncoding default
6 NSSymbolStringEncoding  
7 NSNonLossyASCIIStringEncoding 7-bit verbose ASCII to represent all unichars
8 NSShiftJISStringEncoding  
9 NSISOLatin2StringEncoding  
10 NSUnicodeStringEncoding  
11 NSWindowsCP1251StringEncoding Cyrillic; same as AdobeStandardCyrillic
12 NSWindowsCP1252StringEncoding Windows Latin1
13 NSWindowsCP1253StringEncoding Windows Greek
14 NSWindowsCP1254StringEncoding Windows Turkish
15 NSWindowsCP1250StringEncoding Windows Latin2
21 NSISO2022JPStringEncoding ISO 2022 Japanese encoding for electronic mail


.




Adopted Protocols

NSCopying
- copy
- copyWithZone:


Method Types

Creation
- init
Working with message headers
- appendHeader:forKey:
- appendHeaders:forKey:
- headerForKey:
- headerKeys
- headers
- headersForKey:
- httpVersion
- removeHeadersForKey:
- setHeader:forKey:
- setHeaders:
- setHeaders:forKey:
- setHTTPVersion:
Working with message content
- addCookie:
- appendContentBytes:length:
- appendContentCharacter:
- appendContentData:
- appendContentString:
- content
- cookies
- removeCookie:
- setContent:
Controlling content encoding
+ defaultEncoding
+ setDefaultEncoding:
- contentEncoding
- setContentEncoding:
Working with user info
- setUserInfo:
- userInfo


Class Methods


defaultEncoding

+ (NSStringEncoding)defaultEncoding

Returns the default character encoding used to construct a new WOMessage which initially is NSISOLatin1. For more information, see "Content Encodings".

setDefaultEncoding:

+ (void)setDefaultEncoding:(NSStringEncoding)aStringEncoding

Lets you specify the character encoding to be used by default when construcing a new WOMessage. For more information, see "Content Encodings".


Instance Methods


addCookie:

- (void)addCookie:(WOCookie *)aCookie

A convenience method that adds the specified WOCookie object to the message content.

See Also: - cookies, - removeCookie:, WOCookie class specification


appendContentBytes:length:

- (void)appendContentBytes:(const void *)someBytes length:(unsigned)length

Appends length number of bytes pointed to by someBytes to the HTTP response.

appendContentCharacter:

- (void)appendContentCharacter:(char)aChar

Appends a single ASCII character (aChar) to the message's contents.

Example:

// ...
if (aFlag)
    [aResponse appendContentCharacter:'Y'];
else
    [aResponse appendContentCharacter:'N'];


appendContentData:

- (void)appendContentData:(NSData *)dataObject

Appends a data-encapsulating object (dataObject) to the message's contents.

appendContentString:

- (void)appendContentString:(NSString *)aString

Appends a string to the content of the message's contents. The string is transformed into an NSData object using the receiver's content encoding. The special HTML characters "<", ">", "&", and double-quote are not escaped so a browser can interpret them as HTML.

appendHeader:forKey:

- (void)appendHeader:(NSString *)aHeader forKey:(NSString *)aKey

Appends the HTTP header aHeader to the receiver and associates, for retrieval, the HTTP key aKey with the header. This method is commonly used to set the type of content in a response, for example:
[aResponse appendHeader:@"text/html" forKey:@"content-type"];

See Also: - headerForKey:, - setHeader:forKey:


appendHeaders:forKey:

- (void)appendHeaders:(NSArray *)headerList forKey:(NSString *)aKey

Appends headerList to the list of HTTP headers in the receiver and associates, for retrieval, the HTTP key aKey with the list of header elements. If a header doesn't already exist for the receiver, one is created before the list of headers is appended.

See Also: - headerKeys, - headersForKey:, - setHeaders:forKey:


content

- (NSData *)content

Returns the HTML content of the receiver as an NSData object.

An exception is raised if you attempt to get the content when all elements of the page have not had their chance to append HTML to the response. Thus, you should invoke this method in the application object's handleRequest: method, after super's handleRequest: has been invoked. (For scripted applications, handleRequest: is implemented in Application.wos). Note that at this point in the request-handling process, the components, pages, and session have already been put to sleep, so you won't have access to any context, session, or page information. If you need such information for your response, store it somewhere--such as in WOMessage's "user info" dictionary-at a point when you do have access to it. You may want to do this in your application's appendToResponse:inContext: method, for example.

See Also: - setContent:, - setContentEncoding:


contentEncoding

- (NSStringEncoding)contentEncoding

Returns an integer representing the encoding used for the message's content. See "Content Encodings" in the class description for a mapped list of supported encodings and their WebObjects names. For responses, you will want the response encoding to be the same as that used by the submitting form on the client browser. In this case it is preferable to use WORequest's formValueEncoding.
NSStringEncoding theEncoding = [[aContext request] formValueEncoding];

The default string encoding is ISO Latin1.

See Also: - setContent:, - setContentEncoding:


cookies

- (NSArray *)cookies

A convenience method that returns an array of WOCookie objects to be included in the message (which is uaually a WOResponse).

See Also: - addCookie:, - removeCookie:, WOCookie class specification


headerForKey:

- (NSString *)headerForKey:(NSString *)aKey

Returns the HTTP header information identified by aKey. If there are multiple headers associated with the one key, only the first one is returned. Returns nil if the message has no headers for the key.

See Also: - setHeader:forKey:


headerKeys

- (NSArray *)headerKeys

Returns an array of string keys associated with the receiver's HTTP headers. Returns nil if there are no headers. You could easily test to see if a header is included by doing something similar to this:
NSArray *hKeys =  [aMessage headerKeys];
if ([hKeys containsObject:@"expires"]) {
    // do something
}

See Also: - setHeaders:forKey:


headers

- (NSDictionary *)headers

Returns the header dictionary with which the message was initialized.

headersForKey:

- (NSArray *)headersForKey:(NSString *)aKey

Returns all HTTP headers identified by aKey.

See Also: - setHeaders:forKey:


httpVersion

- (NSString *)httpVersion

Returns the version of HTTP used for the message (for example, "HTTP/1.0").

See Also: - setHTTPVersion:


init

- (id)init

Initializes a WOMessage instance. The default string encoding is made ISO Latin 1.

removeCookie:

- (void)removeCookie:(WOCookie *)aCookie

A convenience method that removes the specified WOCookie object from the message.

See Also: - cookies, - removeCookie:, WOCookie class specification


removeHeadersForKey:

- (void)removeHeadersForKey:(NSString *)aKey

Removes the specified headers from the message.

See Also: - headerKeys, - headersForKey:, - setHeaders:forKey:


setContent:

- (void)setContent:(NSData *)someData

Sets the message contents to someData.

See Also: - content


setContentEncoding:

- (void)setContentEncoding:(NSStringEncoding)anEncoding

Sets the encoding used for the message contents. See "Content Encodings" in the class description for a mapped list of supported encodings and their WebObjects names. The default string encoding is ISO Latin1.

See Also: - contentEncoding


setHTTPVersion:

- (void)setHTTPVersion:(NSString *)aVersion

Sets the version of HTTP used for the message (for example, "HTTP/1.0").

See Also: - httpVersion


setHeader:forKey:

- (void)setHeader:(NSString *)aHeader forKey:(NSString *)aKey

Sets the HTTP header aHeader in the receiver and associates, for retrieval, the HTTP key aKey with the header. This method is commonly used to set the type of content in a response, for example:
[aResponse setHeader:@"text/html" forKey:@"content-type"];

See Also: - appendHeader:forKey:, - headerForKey:


setHeaders:

- (void)setHeaders:(NSDictionary *)headerDictionary

For each key in headerDictionary, appends the corresponding value to the list of HTTP headers in the receiver and associates, for retrieval, the dictionary key with the header value. If a header doesn't already exist for the receiver, one is created before the list of headers is appended.

See Also: - headers, - removeHeadersForKey:


setHeaders:forKey:

- (void)setHeaders:(NSArray *)headerList forKey:(NSString *)aKey

Sets the list of HTTP headers in the receiver to headerList and associates, for retrieval, the HTTP key aKey with the list of header elements. If a header list doesn't already exist for the receiver, one is created before the list of headers is set.

See Also: - appendHeaders:forKey:, - headerKeys, - headersForKey:


setUserInfo:

- (void)setUserInfo:(NSDictionary *)aDictionary

Sets a dictionary in the WOMessage object that, as a convenience, can contain any kind of information related to the current response. Objects further down the appendToResponse:inContext: message "chain" can retrieve this information using userInfo.

userInfo

- (NSDictionary *)userInfo

Returns a dictionary that, as a convenience, can contain any kind of information related to the current response. An object further "upstream" in the appendToResponse:inContext: message "chain" can set this dictionary in the WOMessage object as a way to pass information to other objects.

See Also: - setUserInfo:



Table of Contents