//
//  BEURLUtilities.h
//  AppKit
//
//  Created by Philipp on 3/30/11.
//  Copyright 2011 Incredible Bee Ltd. All rights reserved.
//

#import <Cocoa/Cocoa.h>


@interface NSURL (BEURLUtilities)

/**
 * Returns an URL from a base URL and query parameters
 *
 * @param baseURL The base URL without parameters, for example "http://google.com"
 *
 * @param queryParameters The query parameters with parameter names as keys and
 *                        parameter values as values
 *
 * @return An NSURL object initialized by adding the query parameters to the
 *         base URL. If the resulting URL string is malformed, returns nil.
 *
 * For example to build an URL to search Google:
 *
 *   NSString *baseURL = @"http://google.com/search";
 *   NSDictionary *params = [NSDictionary withObject:@"mainmenu" forKey:@"q"];
 *   NSURL *url = [NSURL URLWithString:baseURL queryParameters:params];
 *
 * The values in the query parameters dictionary are not restricted to
 * NSString. The method will call the values \ref description method, which
 * means you can use NSNumber, NSDate and most simple data types.
 *
 * The method will URL escape the values (but not the keys) of the query
 * parameter values.
 *
 * NSArray data types are not yet supported. Passing an array as a value in the
 * query parameters dictionary won't raise an error but will convert the array
 * to a string, which is probably not what you want.
 *
 * \todo support NSArray as values in \p queryParameters
 */
+(NSURL *) URLWithString:(NSString *)baseURL queryParameters:(NSDictionary *)queryParameters;

/**
 * Initializes and returns an \ref NSURL object in the mailto: URL scheme.
 *
 * @param recipient The email recipient
 *
 * @param subject The email subject or \p nil if no subject
 *
 * @param body The email body or \p nil if no body
 *
 * @return An NSURL object in the \p mailto: URL scheme with the specified
 *         recipient, subject and body.
 *
 * The returned URL is suitable for opening with the user's default mail
 * application:
 *
 *   NSURL *url = [NSURL mailtoURLWithRecipient:@"john@example.com" subject:@"How are you?" body:@"Long time, no hear"];
 *   return [[NSWorkspace sharedWorkspace] openURL:url];
 *
 * Most email applications will on opening the URL start a new mail message
 * and prefil the recipient, subject and body.
 *
 * Tested email applications: Apple Mail, Mailplane.
 *
 * The mailto: URL scheme is covered in RFC 2386:
 *   http://tools.ietf.org/html/rfc2368
 *
 * \todo test more email applications such as Thunderbird
 *
 */
+(NSURL *) mailtoURLWithRecipient:(NSString *)recipient subject:(NSString *)subject body:(NSString *)body;

@end
