ios/web_view/public/cwv_back_forward_list.h

// Copyright 2019 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef IOS_WEB_VIEW_PUBLIC_CWV_BACK_FORWARD_LIST_H_
#define IOS_WEB_VIEW_PUBLIC_CWV_BACK_FORWARD_LIST_H_

#import <UIKit/UIKit.h>

#import "cwv_export.h"

NS_ASSUME_NONNULL_BEGIN

@class CWVBackForwardListItem;
@class CWVWebView;

// This just behaves like a NSArray<CWVBackForwardListItem*>.
//
// |objectAtIndexedSubscript:| and |NSFastEnumeration| are implemented to
// allow to use [] operator and a for-in statement to iterate |self|, like:
//   for (CWVBackForwardListItem* item in backList) { ... }
//   CWVBackForwardListItem* lastItem = backList[backList.count-1];
//
// WARNING: Do not use nested for-in statements to iterate one list at the
// same time, otherwise it will cause a use-after-free bug. Example:
//   for (CWVBackForwardListItem* item in forwardList) {  // OK
//     for (CWVBackForwardListItem* item2 in forwardList) {  // BAD!!
//       // |item| will be deallocated here so the above line is BAD!
//     }
//     // |item| has been deallocated, so using |item| will cause a
//     // use-after-free bug.
//     for (CWVBackForwardListItem* item2 in backList) {}  // OK
//   }
CWV_EXPORT
@interface CWVBackForwardListItemArray : NSObject <NSFastEnumeration>

// The number of items in this array-like |self|.
@property(nonatomic, readonly) NSUInteger count;

// This overloads the [] array-style subscripting operator.
- (CWVBackForwardListItem*)objectAtIndexedSubscript:(NSUInteger)index;

// Instances are supposed to be created only internally.
- (instancetype)init NS_UNAVAILABLE;

@end

// A equivalent of
// https://developer.apple.com/documentation/webkit/wkbackforwardlist
CWV_EXPORT
@interface CWVBackForwardList : NSObject

// A NSArray of CWVBackForwardListItem. The item with the greatest index
// will be closest to current item.
@property(nonatomic, readonly) CWVBackForwardListItemArray* backList;

// A NSArray of CWVBackForwardListItem. The item with index 0 will be
// closest to current item.
@property(nonatomic, readonly) CWVBackForwardListItemArray* forwardList;

// The current item, or nil if there isn't one.
@property(nonatomic, readonly, nullable) CWVBackForwardListItem* currentItem;

// The item in |backList| immediately preceding the current item, or nil if
// there isn't one.
@property(nonatomic, readonly, nullable) CWVBackForwardListItem* backItem;

// The item in |forwardList| immediately following the current item, or nil if
// there isn't one.
@property(nonatomic, readonly, nullable) CWVBackForwardListItem* forwardItem;

// Returns the item at a specified distance from the current item. For the
// meaning of |index|: 0 for the current item, -1 for the immediately preceding
// item, 1 for the immediately following item, and so on (which means |index|
// here is a OFFSET in fact). Returns nil if there isn't one.
- (nullable CWVBackForwardListItem*)itemAtIndex:(NSInteger)index;

- (instancetype)init NS_UNAVAILABLE;

@end

NS_ASSUME_NONNULL_END

#endif  // IOS_WEB_VIEW_PUBLIC_CWV_BACK_FORWARD_LIST_H_