/core/externals/update-engine/externals/gdata-objectivec-client/Source/HTTPFetcher/GTMHTTPFetcherLogging.h

  1/* Copyright (c) 2010 Google Inc.
  2 *
  3 * Licensed under the Apache License, Version 2.0 (the "License");
  4 * you may not use this file except in compliance with the License.
  5 * You may obtain a copy of the License at
  6 *
  7 *     http://www.apache.org/licenses/LICENSE-2.0
  8 *
  9 * Unless required by applicable law or agreed to in writing, software
 10 * distributed under the License is distributed on an "AS IS" BASIS,
 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12 * See the License for the specific language governing permissions and
 13 * limitations under the License.
 14 */
 15
 16#import "GTMHTTPFetcher.h"
 17
 18// GTM HTTP Logging
 19//
 20// All traffic using GTMHTTPFetcher can be easily logged.  Call
 21//
 22//   [GTMHTTPFetcher setLoggingEnabled:YES];
 23//
 24// to begin generating log files.
 25//
 26// Log files are put into a folder on the desktop called "GTMHTTPDebugLogs"
 27// unless another directory is specified with +setLoggingDirectory.
 28//
 29// In the iPhone simulator, the default logs location is the user's home
 30// directory in ~/Library/Application Support.  On the iPhone device, the
 31// default logs location is the application's documents directory on the device.
 32//
 33// Tip: use the Finder's "Sort By Date" to find the most recent logs.
 34//
 35// Each run of an application gets a separate set of log files.  An html
 36// file is generated to simplify browsing the run's http transactions.
 37// The html file includes javascript links for inline viewing of uploaded
 38// and downloaded data.
 39//
 40// A symlink is created in the logs folder to simplify finding the html file
 41// for the latest run of the application; the symlink is called
 42//
 43//   AppName_http_log_newest.html
 44//
 45// For better viewing of XML logs, use Camino or Firefox rather than Safari.
 46//
 47// Each fetcher may be given a comment to be inserted as a label in the logs,
 48// such as
 49//   [fetcher setCommentWithFormat:@"retrieve item %@", itemName];
 50//
 51// Projects may define STRIP_GTM_FETCH_LOGGING to remove logging code.
 52
 53#if !STRIP_GTM_FETCH_LOGGING
 54
 55@interface GTMHTTPFetcher (GTMHTTPFetcherLogging)
 56
 57// Note: the default logs directory is ~/Desktop/GTMHTTPDebugLogs; it will be
 58// created as needed.  If a custom directory is set, the directory should
 59// already exist.
 60+ (void)setLoggingDirectory:(NSString *)path;
 61+ (NSString *)loggingDirectory;
 62
 63// client apps can turn logging on and off
 64+ (void)setLoggingEnabled:(BOOL)flag;
 65+ (BOOL)isLoggingEnabled;
 66
 67// client apps can turn off logging to a file if they want to only check
 68// the fetcher's log property
 69+ (void)setLoggingToFileEnabled:(BOOL)flag;
 70+ (BOOL)isLoggingToFileEnabled;
 71
 72// client apps can optionally specify process name and date string used in
 73// log file names
 74+ (void)setLoggingProcessName:(NSString *)str;
 75+ (NSString *)loggingProcessName;
 76
 77+ (void)setLoggingDateStamp:(NSString *)str;
 78+ (NSString *)loggingDateStamp;
 79
 80// internal; called by fetcher
 81- (void)logFetchWithError:(NSError *)error;
 82- (BOOL)logCapturePostStream;
 83
 84// internal; accessors useful for viewing logs
 85+ (NSString *)processNameLogPrefix;
 86+ (NSString *)symlinkNameSuffix;
 87+ (NSString *)htmlFileName;
 88
 89// Applications may provide alternative body strings to be displayed in the
 90// log, such as for binary requests or responses.  If deferring is turned
 91// on, the response log will not be sent until deferring is turned off,
 92// allowing the application to write the response body after the response
 93// data has been parsed.
 94- (void)setLogRequestBody:(NSString *)bodyString;
 95- (NSString *)logRequestBody;
 96- (void)setLogResponseBody:(NSString *)bodyString;
 97- (NSString *)logResponseBody;
 98- (void)setShouldDeferResponseBodyLogging:(BOOL)flag;
 99- (BOOL)shouldDeferResponseBodyLogging;
100
101@end
102
103#endif  // !STRIP_GTM_FETCH_LOGGING