nsIRequestContext.idl (4685B)
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #include "nsISupports.idl" 7 8 interface nsILoadGroup; 9 interface nsIChannel; 10 interface nsIStreamListener; 11 12 /** 13 * Requests capable of tail-blocking must implement this 14 * interfaces (typically channels). 15 * If the request is tail-blocked, it will be held in its request 16 * context queue until unblocked. 17 */ 18 [uuid(7EB361D4-37A5-42C9-AFAE-F6C88FE7C394)] 19 interface nsIRequestTailUnblockCallback : nsISupports 20 { 21 /** 22 * Called when the requests is unblocked and proceed. 23 * @param result 24 * NS_OK - the request is OK to go, unblocking is not 25 * caused by cancelation of the request. 26 * any error - the request must behave as it were canceled 27 * with the result as status. 28 */ 29 void onTailUnblock(in nsresult aResult); 30 }; 31 32 /** 33 * The nsIRequestContext is used to maintain state about connections 34 * that are in some way associated with each other (often by being part 35 * of the same load group) and how they interact with blocking items like 36 * HEAD css/js loads. 37 * 38 * This used to be known as nsILoadGroupConnectionInfo and nsISchedulingContext. 39 */ 40 [uuid(658e3e6e-8633-4b1a-8d66-fa9f72293e63)] 41 interface nsIRequestContext : nsISupports 42 { 43 /** 44 * A unique identifier for this request context 45 */ 46 [notxpcom, nostdcall] readonly attribute unsigned long long ID; 47 48 /** 49 * Called by the associated document when its load starts. This resets 50 * context's internal states. 51 */ 52 void beginLoad(); 53 54 /** 55 * Called when the associated document notified the DOMContentLoaded event. 56 */ 57 void DOMContentLoaded(); 58 59 /** 60 * Number of active blocking transactions associated with this context 61 */ 62 readonly attribute unsigned long blockingTransactionCount; 63 64 /** 65 * Increase the number of active blocking transactions associated 66 * with this context by one. 67 */ 68 void addBlockingTransaction(); 69 70 /** 71 * Decrease the number of active blocking transactions associated 72 * with this context by one. The return value is the number of remaining 73 * blockers. 74 */ 75 unsigned long removeBlockingTransaction(); 76 77 /** 78 * Increases/decrease the number of non-tailed requests in this context. 79 * If the count drops to zero, all tail-blocked callbacks are notified 80 * shortly after that to be unblocked. 81 */ 82 void addNonTailRequest(); 83 void removeNonTailRequest(); 84 85 /** 86 * If the request context is in tail-blocked state, the callback 87 * is queued and result is true. The callback will be notified 88 * about tail-unblocking or when the request context is canceled. 89 */ 90 [must_use] boolean isContextTailBlocked(in nsIRequestTailUnblockCallback callback); 91 92 /** 93 * Called when the request is sitting in the tail queue but has been 94 * canceled before untailing. This just removes the request from the 95 * queue so that it is not notified on untail and not referenced. 96 */ 97 void cancelTailedRequest(in nsIRequestTailUnblockCallback request); 98 99 /** 100 * This notifies all queued tail-blocked requests, they will be notified 101 * aResult and released afterwards. Called by the load group when 102 * it's canceled. 103 */ 104 void cancelTailPendingRequests(in nsresult aResult); 105 }; 106 107 /** 108 * The nsIRequestContextService is how anyone gets access to a request 109 * context when they haven't been explicitly given a strong reference to an 110 * existing one. It is responsible for creating and handing out strong 111 * references to nsIRequestContexts, but only keeps weak references itself. 112 * The shared request context will go away once no one else is keeping a 113 * reference to it. If you ask for a request context that has no one else 114 * holding a reference to it, you'll get a brand new request context. Anyone 115 * who asks for the same request context while you're holding a reference 116 * will get a reference to the same request context you have. 117 */ 118 [uuid(7fcbf4da-d828-4acc-b144-e5435198f727)] 119 interface nsIRequestContextService : nsISupports 120 { 121 /** 122 * Get an existing request context from its ID 123 */ 124 nsIRequestContext getRequestContext(in unsigned long long id); 125 /** 126 * Shorthand to get request context from a load group 127 */ 128 nsIRequestContext getRequestContextFromLoadGroup(in nsILoadGroup lg); 129 130 /** 131 * Create a new request context 132 */ 133 nsIRequestContext newRequestContext(); 134 135 /** 136 * Remove an existing request context from its ID 137 */ 138 void removeRequestContext(in unsigned long long id); 139 };