//
//  SKDataUpload.h
//  SpeechKit
//
// Copyright 2012, Nuance Communications Inc. All rights reserved.
//
// Nuance Communications, Inc. provides this document without representation 
// or warranty of any kind. The information in this document is subject to 
// change without notice and does not represent a commitment by Nuance 
// Communications, Inc. The software and/or databases described in this 
// document are furnished under a license agreement and may be used or 
// copied only in accordance with the terms of such license agreement.  
// Without limiting the rights under copyright reserved herein, and except 
// as permitted by such license agreement, no part of this document may be 
// reproduced or transmitted in any form or by any means, including, without 
// limitation, electronic, mechanical, photocopying, recording, or otherwise, 
// or transferred to information storage and retrieval systems, without the 
// prior written permission of Nuance Communications, Inc.
// 
// Nuance, the Nuance logo, Nuance Recognizer, and Nuance Vocalizer are 
// trademarks or registered trademarks of Nuance Communications, Inc. or its 
// affiliates in the United States and/or other countries. All other 
// trademarks referenced herein are the property of their respective owners.
//

#import <Foundation/Foundation.h>
#import <SpeechKit/SKDataUploadResult.h>
#import <SpeechKit/DataBlock.h>


@protocol SKDataUploadDelegate;


/*!
 @discussion The SKDataUpload class manages a single data upload command
 SKDataUpload is designed to carry out a single command 
 so after receiving the response the class should be released. Subsequent results 
 should each be generated by instantiating a new SKDataUpload instance.
 */
@interface SKDataUpload : NSObject
{
    id<SKDataUploadDelegate> delegate;
}

@property (nonatomic, assign) id <SKDataUploadDelegate> delegate;

/*!
 @abstract Returns an initialized data upload command and begins the uploading process.
 
 @param datablock data block to be uploaded
 @param currentChecksum is the checksum from the previous data upload. This is 
 to make sure that both device and server are in synch before even  performing 
 the new update. If they are not, the server does not process this command 
 and asks to repeat the upload.
 @param newChecksum the checksum during this command
 @param delegate The receiver for uploading responses.  The delegate must
 implement the SKDataUploadDelegate protocol and will receive a message when the
 uploading process has completed.
 @result A data upload object corresponding to the command.
 */
- (id)initWithDataUpload:(DataBlock *)datablock currentChecksum:(int)curChecksum newChecksum:(int)newChecksum delegate:(id <SKDataUploadDelegate>)aDelegate;

 /*!
 @abstract Cancels the command request.
 
 @discussion This method will terminate the command request.  This will result 
 in the delegate receiving an error message via the 
 dataupload:didFinishWithError:suggestion method unless a command result 
 has been or is already being sent to the delegate.
 */
- (void)cancel;

@end


 /*!
 @discussion The SKDataUploadDelegate protocol defines the messages sent to a 
 delegate of the SKDataUpload class.  These delegate methods indicate the flow 
 of the command process.  The receiver will be notified when the command is finished
 or has error.
 */
@protocol SKDataUploadDelegate <NSObject>

@required
/*!
 @abstract Sent when the command completes successfully.
 
 @param command The data upload command
 @param results The SKDataUploadResult object containing the data result list.
 
 @discussion This method is only called when the command completes 
 successfully.
 */
- (void)dataupload:(SKDataUpload *)command didFinishWithResults:(SKDataUploadResult *)results;

/*!
 @abstract Sent when the command completes with an error.
 
 @param command The data upload command
 @param error The command error. Possible numeric values for the 
 SKSpeechErrorDomain are listed in SpeechKitError.h and a text description is
 available via the localizedDescription method.
 @param suggestion This is a suggestion to the user about how he or she can 
 improve the command process.
 
 @discussion This method is called when the comand results in an 
 error due to any number of circumstances. The server connection may be disrupted 
 or a parameter specified during initialization, such as language or authentication 
 information was invalid.
 */
- (void)dataupload:(SKDataUpload *)command didFinishWithError:(NSError *)error suggestion:(NSString *)suggestion;

@end