//
//  KGLeaderboard.h
//  KakaoGame SDK
//
//  Created by Ronaldo Kim on 2016. 9. 19..
//  Copyright (c) 2016. Kakao Corp. All rights reserved.
//

#import <Foundation/Foundation.h>
#import <KakaoGame/KGRankingInfo.h>

/**
 * @brief KGLeaderboard클래스는 리더보드 기능을 제공한다.
 */
@interface KGLeaderboard : NSObject

/**
 * @brief 리더보드에 점수를 등록한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param score 점수.
 * @param completionHandler 완료 핸들러 [error:등록 결과].
 */
+ (void)reportScoreWithLeaderboardId:(NSString *)leaderboardId
                               score:(long long)score
                   completionHandler:(void(^)(NSError *error))completionHandler;

/**
 * @brief 리더보드에 점수를 누적한다.<br>
 * 기존에 등록된 점수가 없으면, 0값에 누적된다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param score 점수.
 * @param completionHandler 완료 핸들러 [error:등록 결과].
 */
+ (void)accumulateScoreWithLeaderboardId:(NSString *)leaderboardId
                                   score:(long long)score
                       completionHandler:(void(^)(NSError *error))completionHandler;

/**
 * @brief 랭킹 속성의 저장을 요청한다.
 *
 * @param properties 랭킹 속성 데이터.
 * @param completionHandler 완료 핸들러 [error:저장 결과].
 */
+ (void)saveRankingProperties:(NSDictionary *)properties completionHandler:(void (^)(NSError *error))completionHandler;

/**
 * @brief 랭킹 속성의 저장을 요청한다.
 *
 * @param aProperty 랭킹 속성 값.
 * @param aKey 랭킹 속성 키.
 * @param completionHandler 완료 핸들러 [error:저장 결과].
 */
+ (void)saveRankingProperty:(NSString *)aProperty forKey:(NSString *)aKey completionHandler:(void(^)(NSError *error))completionHandler;

/**
 * @brief 현재 시즌의 내 랭킹 정보를 조회한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param completionHandler 완료 핸들러 [error:조회 결과][rankingInfo:랭킹 정보][totalPlayerCount:리더보드의 전체 사용자 수].
 *
 * @see KGRankingInfo
 */
+ (void)loadMyRankingWithLeaderboardId:(NSString *)leaderboardId
                     completionHandler:(void(^)(NSError *error, KGRankingInfo *rankingInfo, int totalPlayerCount))completionHandler;

/**
 * @brief 이전 시즌의 내 랭킹 정보를 조회한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param completionHandler 완료 핸들러 [error:조회 결과][rankingInfo:랭킹 정보][totalPlayerCount:리더보드의 전체 사용자 수].
 *
 * @see KGRankingInfo
 */
+ (void)loadLastSeasonMyRankingWithLeaderboardId:(NSString *)leaderboardId
                               completionHandler:(void(^)(NSError *error, KGRankingInfo *rankingInfo, int totalPlayerCount))completionHandler;

/**
 * @brief 현재 시즌의 순위에 해당하는 랭킹 정보 목록를 조회한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param beginRank 조회할 시작 등수.<br>1보다 크거나 같아야 한다.
 * @param endRank 조회할 마지막 등수.<br>시작 등수보다 크거나 같아야 한다. 최대 1000등까지 지원한다.
 * @param completionHandler 완료 핸들러 [error:조회 결과][rankingInfos:랭킹 정보 목록][totalPlayerCount:리더보드의 전체 사용자 수].
 *
 * @see KGRankingInfo
 */
+ (void)loadRankingsWithLeaderboardId:(NSString *)leaderboardId
                            beginRank:(int)beginRank
                              endRank:(int)endRank
                    completionHandler:(void(^)(NSError *error, NSArray *rankingInfos, int totalPlayerCount))completionHandler;

/**
 * @brief 이전 시즌의 순위에 해당하는 랭킹 정보 목록를 조회한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param beginRank 조회할 시작 등수.<br>1보다 크거나 같아야 한다.
 * @param endRank 조회할 마지막 등수.<br>시작 등수보다 크거나 같아야 한다. 최대 1000등까지 지원한다.
 * @param completionHandler 완료 핸들러 [error:조회 결과][rankingInfos:랭킹 정보 목록][totalPlayerCount:리더보드의 전체 사용자 수].
 *
 * @see KGRankingInfo
 */
+ (void)loadLastSeasonRankingsWithLeaderboardId:(NSString *)leaderboardId
                                      beginRank:(int)beginRank
                                        endRank:(int)endRank
                              completionHandler:(void(^)(NSError *error, NSArray *rankingInfos, int totalPlayerCount))completionHandler;

/**
 * @brief 리더보드에 점수를 등록한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param subkey 리더보드 서브키.
 * @param score 점수.
 * @param completionHandler 완료 핸들러 [error:등록 결과].
 */
+ (void)reportScoreWithLeaderboardId:(NSString *)leaderboardId
							  subkey:(NSString *)subkey
							   score:(long long)score
				   completionHandler:(void(^)(NSError *error))completionHandler;

/**
 * @brief 리더보드에 점수를 누적한다.<br>
 * 기존에 등록된 점수가 없으면, 0값에 누적된다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param subkey 리더보드 서브키.
 * @param score 점수.
 * @param completionHandler 완료 핸들러 [error:등록 결과].
 */
+ (void)accumulateScoreWithLeaderboardId:(NSString *)leaderboardId
								  subkey:(NSString *)subkey
								   score:(long long)score
					   completionHandler:(void(^)(NSError *error))completionHandler;

/**
 * @brief 랭킹 속성의 저장을 요청한다.
 *
 * @param subkey 리더보드 서브키.
 * @param properties 랭킹 속성 데이터.
 * @param completionHandler 완료 핸들러 [error:저장 결과].
 */
+ (void)saveRankingPropertiesWithSubkey:(NSString *)subkey
							 properties:(NSDictionary *)properties
					  completionHandler:(void (^)(NSError *error))completionHandler;

/**
 * @brief 랭킹 속성의 저장을 요청한다.
 *
 * @param subkey 리더보드 서브키.
 * @param aProperty 랭킹 속성 값.
 * @param aKey 랭킹 속성 키.
 * @param completionHandler 완료 핸들러 [error:저장 결과].
 */
+ (void)saveRankingPropertyWithSubkey:(NSString *)subkey
							 property:(NSString *)aProperty
							   forKey:(NSString *)aKey
					completionHandler:(void(^)(NSError *error))completionHandler;

/**
 * @brief 현재 시즌의 내 랭킹 정보를 조회한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param subkey 리더보드 서브키.
 * @param completionHandler 완료 핸들러 [error:조회 결과][rankingInfo:랭킹 정보][totalPlayerCount:리더보드의 전체 사용자 수].
 *
 * @see KGRankingInfo
 */
+ (void)loadMyRankingWithLeaderboardId:(NSString *)leaderboardId
								subkey:(NSString *)subkey
					 completionHandler:(void(^)(NSError *error, KGRankingInfo *rankingInfo, int totalPlayerCount))completionHandler;

/**
 * @brief 이전 시즌의 내 랭킹 정보를 조회한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param subkey 리더보드 서브키.
 * @param completionHandler 완료 핸들러 [error:조회 결과][rankingInfo:랭킹 정보][totalPlayerCount:리더보드의 전체 사용자 수].
 *
 * @see KGRankingInfo
 */
+ (void)loadLastSeasonMyRankingWithLeaderboardId:(NSString *)leaderboardId
										  subkey:(NSString *)subkey
							   completionHandler:(void(^)(NSError *error, KGRankingInfo *rankingInfo, int totalPlayerCount))completionHandler;

/**
 * @brief 현재 시즌의 순위에 해당하는 랭킹 정보 목록를 조회한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param subkey 리더보드 서브키.
 * @param beginRank 조회할 시작 등수.<br>1보다 크거나 같아야 한다.
 * @param endRank 조회할 마지막 등수.<br>시작 등수보다 크거나 같아야 한다. 최대 1000등까지 지원한다.
 * @param completionHandler 완료 핸들러 [error:조회 결과][rankingInfos:랭킹 정보 목록][totalPlayerCount:리더보드의 전체 사용자 수].
 *
 * @see KGRankingInfo
 */
+ (void)loadRankingsWithLeaderboardId:(NSString *)leaderboardId
							   subkey:(NSString *)subkey
							beginRank:(int)beginRank
							  endRank:(int)endRank
					completionHandler:(void(^)(NSError *error, NSArray *rankingInfos, int totalPlayerCount))completionHandler;

/**
 * @brief 이전 시즌의 순위에 해당하는 랭킹 정보 목록를 조회한다.
 *
 * @param leaderboardId 리더보드 아이디.
 * @param subkey 리더보드 서브키.
 * @param beginRank 조회할 시작 등수.<br>1보다 크거나 같아야 한다.
 * @param endRank 조회할 마지막 등수.<br>시작 등수보다 크거나 같아야 한다. 최대 1000등까지 지원한다.
 * @param completionHandler 완료 핸들러 [error:조회 결과][rankingInfos:랭킹 정보 목록][totalPlayerCount:리더보드의 전체 사용자 수].
 *
 * @see KGRankingInfo
 */
+ (void)loadLastSeasonRankingsWithLeaderboardId:(NSString *)leaderboardId
										 subkey:(NSString *)subkey
									  beginRank:(int)beginRank
										endRank:(int)endRank
							  completionHandler:(void(^)(NSError *error, NSArray *rankingInfos, int totalPlayerCount))completionHandler;

@end
