Cursor-API

官網：https://developer.android.google.cn/reference/android/database/Cursor

光標

科特林 |爪哇

public interface Cursor 
implements Closeable

android.database.Cursor

已知間接子類

抽象電流, 文摘窗口, 交叉過程電流, 交叉過程CursorWrapper, CursorWrapper, MatrixCursor, 默格柯薩, 莫克柯莎, SQLiteCursor

 

---

此接口提供對數據庫查詢返回的結果集的隨機讀寫訪問。

遊標實現不需要同步，因此使用來自多個線程的遊標的代碼在使用遊標時應該執行自己的同步。

實現應該子類AbstractCursor.

 

摘要

常數
int	FIELD_TYPE_BLOB 返回值getType(int)如果指定的列類型爲BLOB
int	FIELD_TYPE_FLOAT 返回值getType(int)如果指定的列類型是浮動的
int	FIELD_TYPE_INTEGER 返回值getType(int)如果指定的列類型爲整數
int	FIELD_TYPE_NULL 返回值getType(int)如果指定的列爲空
int	FIELD_TYPE_STRING 返回值getType(int)如果指定的列類型爲字符串

公共方法
abstract void	close() 關閉遊標，釋放其所有資源並使其完全無效。
abstract void	copyStringToBuffer(int columnIndex, CharArrayBuffer buffer) 檢索請求的列文本並將其存儲在提供的緩衝區中。
abstract void	deactivate() 此方法在API級別16中被廢棄。requery()是不受歡迎的，這個也是。
abstract byte[]	getBlob(int columnIndex) 將請求列的值作爲字節數組返回。
abstract int	getColumnCount() 返回列總數
abstract int	getColumnIndex(String columnName) 返回給定列名的基於零的索引，如果該列不存在，則返回-1。
abstract int	getColumnIndexOrThrow(String columnName) 返回給定列名的基於零的索引，或引發IllegalArgumentException如果列不存在。
abstract String	getColumnName(int columnIndex) 返回給定的基於零的列索引處的列名。
abstract String[]	getColumnNames() 返回一個字符串數組，該數組按結果中列出的所有列的順序保存結果集中所有列的名稱。
abstract int	getCount() 返回光標中的行數。
abstract double	getDouble(int columnIndex) 將請求列的值作爲Double返回。
abstract Bundle	getExtras() 返回多個附加值。
abstract float	getFloat(int columnIndex) 將請求列的值作爲浮動返回。
abstract int	getInt(int columnIndex) 將請求列的值作爲int返回。
abstract long	getLong(int columnIndex) 將請求列的值作爲Long返回。
abstract Uri	getNotificationUri() 返回將傳遞此遊標數據更改通知的URI，正如先前由setNotificationUri(ContentResolver, Uri).
default List<Uri>	getNotificationUris() 返回此遊標數據更改通知將在其中傳遞的URI，如先前由setNotificationUris(ContentResolver, List).
abstract int	getPosition() 返回光標在行集中的當前位置。
abstract short	getShort(int columnIndex) 將請求列的值作爲簡短返回。
abstract String	getString(int columnIndex) 將請求列的值作爲字符串返回。
abstract int	getType(int columnIndex) 返回給定列的值的數據類型。
abstract boolean	getWantsAllOnMoveCalls() 只有當此方法返回true時，onMove()纔會跨進程調用。
abstract boolean	isAfterLast() 返回光標是否指向最後一行之後的位置。
abstract boolean	isBeforeFirst() 返回光標是否指向第一行之前的位置。
abstract boolean	isClosed() 如果遊標關閉，則返回true
abstract boolean	isFirst() 返回光標是否指向第一行。
abstract boolean	isLast() 返回光標是否指向最後一行。
abstract boolean	isNull(int columnIndex) 回報true如果指定列中的值爲NULL。
abstract boolean	move(int offset) 將光標從當前位置向前或向後移動一個相對數量。
abstract boolean	moveToFirst() 將光標移動到第一行。
abstract boolean	moveToLast() 將光標移到最後一行。
abstract boolean	moveToNext() 將光標移動到下一行。
abstract boolean	moveToPosition(int position) 將光標移動到絕對位置。
abstract boolean	moveToPrevious() 將光標移動到上一行。
abstract void	registerContentObserver(ContentObserver observer) 註冊當支持此遊標的內容發生更改時調用的觀察者。
abstract void	registerDataSetObserver(DataSetObserver observer) 註冊當此遊標數據集的內容發生更改時調用的觀察者，例如，當數據集通過requery(), deactivate()，或close().
abstract boolean	requery() 此方法在API級別15中被廢棄。請不要使用此方法。只需請求一個新的遊標，這樣您就可以異步完成此操作，並在新遊標返回後更新您的列表視圖。
abstract Bundle	respond(Bundle extras) 這是遊標用戶與光標通信的一種帶外方式。
abstract void	setExtras(Bundle extras) 設置Bundle將由getExtras().
abstract void	setNotificationUri(ContentResolver cr, Uri uri) 註冊以查看更改的內容URI。
default void	setNotificationUris(ContentResolver cr, List<Uri> uris) 類似於setNotificationUri(android.content.ContentResolver, android.net.Uri)，但此版本允許查看多個內容URI以進行更改。
abstract void	unregisterContentObserver(ContentObserver observer) 註銷以前在此遊標中註冊的觀察者。registerContentObserver(ContentObserver).
abstract void	unregisterDataSetObserver(DataSetObserver observer) 註銷以前在此遊標中註冊的觀察者。registerContentObserver(ContentObserver).

遺傳方法

從接口 java.io.Closeable

從接口 java.lang.AutoCloseable

常數

場型水滴

加進空氣污染指數第11級

public static final int FIELD_TYPE_BLOB

返回值getType(int)如果指定的列類型爲BLOB

 

常數：4(0x00000004)

場式浮子

加進空氣污染指數第11級

public static final int FIELD_TYPE_FLOAT

返回值getType(int)如果指定的列類型是浮動的

 

常數：2(0x00000002)

字段型整數

加進空氣污染指數第11級

public static final int FIELD_TYPE_INTEGER

返回值getType(int)如果指定的列類型爲整數

 

常數：1(0x00000001)

字段型空

加進空氣污染指數第11級

public static final int FIELD_TYPE_NULL

返回值getType(int)如果指定的列爲空

 

常數：0(0x00000000)

字段型字符串

加進空氣污染指數第11級

public static final int FIELD_TYPE_STRING

返回值getType(int)如果指定的列類型爲字符串

 

常數：3(0x00000003)

公共方法

關

加進API一級

public abstract void close ()

關閉遊標，釋放其所有資源並使其完全無效。不像deactivate()打電話給requery()將不再使光標有效。

 

CopyStringToBuffer

加進API一級

public abstract void copyStringToBuffer (int columnIndex, 
                CharArrayBuffer buffer)

檢索請求的列文本並將其存儲在提供的緩衝區中。如果緩衝區大小不夠，將分配一個新的char緩衝區並分配給ChararrayBuffer.data

 

參數
columnIndex	int目標列的基於零的索引。如果目標列爲空，則返回緩衝區。
buffer	CharArrayBuffer要將文本複製到的緩衝區。

停用

加進API一級 
不受歡迎API第16級

public abstract void deactivate ()

 

API級別16中不推薦此方法。
自requery()是不受歡迎的，這個也是。

取消遊標，使其上的所有調用都失敗，直到requery()叫做。非活動遊標使用的資源比活動遊標少。呼叫requery()將使光標再次活動。

 

蓋布洛布

加進API一級

public abstract byte[] getBlob (int columnIndex)

將請求列的值作爲字節數組返回。

結果以及當列值爲NULL或列類型不是BLOB類型時，此方法是否引發異常都是實現定義的。

 

參數
columnIndex	int目標列的基於零的索引。

回報
byte[]	該列作爲字節數組的值。

[計]哥倫布數

加進API一級

public abstract int getColumnCount ()

返回列總數

 

回報
int	欄數

getColumnIndex

加進API一級

public abstract int getColumnIndex (String columnName)

返回給定列名的基於零的索引，如果該列不存在，則返回-1。如果希望列存在，請使用getColumnIndexOrThrow(java.lang.String)相反，這將使錯誤更加清楚。

 

參數
columnName	String目標列的名稱。

回報
int	給定列名的基於零的列索引，如果列名不存在，則爲-1。

另見：

• getColumnIndexOrThrow(String)

getColumnIndexOrThrow

加進API一級

public abstract int getColumnIndexOrThrow (String columnName)

返回給定列名的基於零的索引，或引發IllegalArgumentException如果列不存在。如果您不確定某列是否存在或不使用getColumnIndex(java.lang.String)並檢查-1，這比捕獲異常更有效。

 

參數
columnName	String目標列的名稱。

回報
int	給定列名的基於零的列索引。

拋出
IllegalArgumentException	如果列不存在

另見：

• getColumnIndex(String)

getColumnName

加進API一級

public abstract String getColumnName (int columnIndex)

返回給定的基於零的列索引處的列名。

 

參數
columnIndex	int目標列的基於零的索引。

回報
String	給定列索引的列名。

getColumnNames

加進API一級

public abstract String[] getColumnNames ()

返回一個字符串數組，該數組按結果中列出的所有列的順序保存結果集中所有列的名稱。

 

回報
String[]	此查詢中返回的列的名稱。

getCount

加進API一級

public abstract int getCount ()

返回光標中的行數。

 

回報
int	光標中的行數。

蓋杜布爾

加進API一級

public abstract double getDouble (int columnIndex)

將請求列的值作爲Double返回。

結果以及當列值爲空、列類型不是浮點類型或浮點值不能表示爲double值是實現定義的。

 

參數
columnIndex	int目標列的基於零的索引。

回報
double	該列的值爲Double。

getExtras

加進API一級

public abstract Bundle getExtras ()

返回多個附加值。這是遊標向用戶提供帶外元數據的可選方式.其中一種用途是報告爲遊標獲取數據所需的網絡請求的進度。

只有在調用請求時，這些值纔可能更改。

 

回報
Bundle	遊標定義的值，或Bundle.EMPTY如果沒有價值。絕不可能null.

getFloat

加進API一級

public abstract float getFloat (int columnIndex)

將請求列的值作爲浮動返回。

結果以及當列值爲空、列類型不是浮點類型或浮點值不能表示爲float值是實現定義的。

 

參數
columnIndex	int目標列的基於零的索引。

回報
float	該列作爲浮點數的值。

getInt

加進API一級

public abstract int getInt (int columnIndex)

將請求列的值作爲int返回。

結果以及當列值爲空、列類型不是整型或整數值超出範圍時，此方法是否引發異常[Integer.MIN_VALUE,Integer.MAX_VALUE]是實現-定義的。

 

參數
columnIndex	int目標列的基於零的索引。

回報
int	該列的值爲int。

吉龍

加進API一級

public abstract long getLong (int columnIndex)

將請求列的值作爲Long返回。

結果以及當列值爲空、列類型不是整型或整數值超出範圍時，此方法是否引發異常[Long.MIN_VALUE,Long.MAX_VALUE]是實現-定義的。

 

參數
columnIndex	int目標列的基於零的索引。

回報
long	那列的值是長的。

getNotificationURI

加進空氣污染指數第19級

public abstract Uri getNotificationUri ()

返回將傳遞此遊標數據更改通知的URI，正如先前由setNotificationUri(ContentResolver, Uri).

 

回報
Uri	返回可與ContentResolver#registerContentObserver(android.net.Uri, boolean, ContentObserver)若要了解對此遊標數據的更改，請執行以下操作。如果沒有設置通知URI，則可能爲空。

getNotificationUris

加進空氣污染指數第29級

public List<Uri> getNotificationUris ()

返回此遊標數據更改通知將在其中傳遞的URI，如先前由setNotificationUris(ContentResolver, List).

如果沒有實現這一點，這相當於調用getNotificationUri().

 

回報
List<Uri>	返回可以與ContentResolver#registerContentObserver(android.net.Uri, boolean, ContentObserver)若要了解對此遊標數據的更改，請執行以下操作。如果沒有設置通知URI，則可能爲空。

獲取位置

加進API一級

public abstract int getPosition ()

返回光標在行集中的當前位置。這個值是基於零的。當第一次返回行集時，光標將位於位置-1，位於第一行之前。在返回最後一行之後，對Next()的另一個調用將使遊標在最後一個條目之後，位於count()的位置。

 

回報
int	當前光標的位置。

getShort

加進API一級

public abstract short getShort (int columnIndex)

將請求列的值作爲簡短返回。

結果以及當列值爲空、列類型不是整型或整數值超出範圍時，此方法是否引發異常[Short.MIN_VALUE,Short.MAX_VALUE]是實現-定義的。

 

參數
columnIndex	int目標列的基於零的索引。

回報
short	該列的值爲短。

getString

加進API一級

public abstract String getString (int columnIndex)

將請求列的值作爲字符串返回。

當列值爲NULL或列類型不是字符串類型時，該方法是否引發異常的結果是實現定義的。

 

參數
columnIndex	int目標列的基於零的索引。

回報
String	該列的值爲字符串。

getType

加進空氣污染指數第11級

public abstract int getType (int columnIndex)

返回給定列的值的數據類型。返回列的首選類型，但數據可以轉換爲其他類型，如get-type方法中記錄的那樣。getInt(int), getFloat(int)等。

返回的列類型爲

• FIELD_TYPE_NULL
• FIELD_TYPE_INTEGER
• FIELD_TYPE_FLOAT
• FIELD_TYPE_STRING
• FIELD_TYPE_BLOB

 

 

 

參數
columnIndex	int目標列的基於零的索引。

回報
int	列值類型

getWantsAllOnMoveCalls

加進API一級

public abstract boolean getWantsAllOnMoveCalls ()

只有當此方法返回true時，onMove()纔會跨進程調用。

 

回報
boolean	是否所有光標的移動都會導致對onMove()的調用。

最後一次

加進API一級

public abstract boolean isAfterLast ()

返回光標是否指向最後一行之後的位置。

 

回報
boolean	光標是否在最後一個結果之後。

第一

加進API一級

public abstract boolean isBeforeFirst ()

返回光標是否指向第一行之前的位置。

 

回報
boolean	光標是否在第一個結果之前。

等閉

加進API一級

public abstract boolean isClosed ()

如果遊標關閉，則返回true

 

回報
boolean	如果光標關閉，則爲true。

ISFirst

加進API一級

public abstract boolean isFirst ()

返回光標是否指向第一行。

 

回報
boolean	光標是否指向第一個條目。

最後一次

加進API一級

public abstract boolean isLast ()

返回光標是否指向最後一行。

 

回報
boolean	光標是否指向最後一個條目。

isNull

加進API一級

public abstract boolean isNull (int columnIndex)

回報true如果指定列中的值爲NULL。

 

參數
columnIndex	int目標列的基於零的索引。

回報
boolean	列值是否爲空。

移動

加進API一級

public abstract boolean move (int offset)

將光標從當前位置向前或向後移動一個相對數量。正偏移向前移動，負偏移向後移動。如果最後一個位置超出了結果集的界限，則結果位置將被固定爲-1或count()，這取決於該值分別是在集合的前端還是末尾。

如果請求的目標可達，此方法將返回true，否則將返回false。例如，如果光標當前位於結果集中的第二個條目上，並且調用了Move(-5)，則位置將固定在-1，並返回false。

 

參數
offset	int*從當前職位適用的抵消額。

回報
boolean	請求的移動是否完全成功。

MoveToFirst

加進API一級

public abstract boolean moveToFirst ()

將光標移動到第一行。

如果遊標爲空，此方法將返回false。

 

回報
boolean	行動是否成功。

移動到最後

加進API一級

public abstract boolean moveToLast ()

將光標移到最後一行。

如果遊標爲空，此方法將返回false。

 

回報
boolean	行動是否成功。

MoveToNext

加進API一級

public abstract boolean moveToNext ()

將光標移動到下一行。

如果遊標已經超過結果集中的最後一個條目，此方法將返回false。

 

回報
boolean	行動是否成功。

動位

加進API一級

public abstract boolean moveToPosition (int position)

將光標移動到絕對位置。有效的值範圍是-1<=位置<=計數。

如果請求目標可達，此方法將返回true，否則將返回false。

 

參數
position	int要移動到的基於零的位置。

回報
boolean	請求的移動是否完全成功。

動感

加進API一級

public abstract boolean moveToPrevious ()

將光標移動到上一行。

如果遊標已經在結果集中的第一個條目之前，此方法將返回false。

 

回報
boolean	行動是否成功。

寄存器內容觀察員

加進API一級

public abstract void registerContentObserver (ContentObserver observer)

註冊當支持此遊標的內容發生更改時調用的觀察者。通常情況下，數據集直到requery()叫做。

 

參數
observer	ContentObserver：當支持遊標的內容發生更改時得到通知的對象。

另見：

• unregisterContentObserver(ContentObserver)

寄存器數據設置觀察者

加進API一級

public abstract void registerDataSetObserver (DataSetObserver observer)

註冊當此遊標數據集的內容發生更改時調用的觀察者，例如，當數據集通過requery(), deactivate()，或close().

 

參數
observer	DataSetObserver當遊標數據集更改時得到通知的對象。

另見：

• unregisterDataSetObserver(DataSetObserver)

請求

加進API一級 
不受歡迎空氣污染指數第15級

public abstract boolean requery ()

 

API級別15中不推薦此方法。
別用這個。只需請求一個新的遊標，這樣您就可以異步完成此操作，並在新遊標返回後更新您的列表視圖。

執行再次創建遊標的查詢，刷新其內容。這可以在任何時候進行，包括在呼叫deactivate()。由於此方法可以在數據庫上執行查詢，並且可能需要一段時間，因此如果在main(UI)線程上調用該方法，可能會導致ANR。如果在主線程上執行此方法，則會打印警告。

 

回報
boolean	如果請求成功，則爲true，否則爲false，則光標無效。

迴應

加進API一級

public abstract Bundle respond (Bundle extras)

這是遊標用戶與光標通信的一種帶外方式。每個包的結構完全由遊標定義。

其中一種方法是告訴遊標在報告錯誤後應該重試其網絡請求。

 

參數
extras	Bundle*額外價值，或Bundle.EMPTY。絕不可能null.

回報
Bundle	額外價值，或Bundle.EMPTY。絕不可能null.

SETExtras

加進API 23級

public abstract void setExtras (Bundle extras)

設置Bundle將由getExtras().

 

參數
extras	Bundle: Bundle設置或NULL設置空包。

setNotificationURI

加進API一級

public abstract void setNotificationUri (ContentResolver cr, 
                Uri uri)

註冊以查看更改的內容URI。這可以是特定數據行的URI(例如，“content：//my_Provider_type/23”)，也可以是內容類型的通用URI。

調用此命令將重寫以前對setNotificationUris(android.content.ContentResolver, java.util.List).

 

參數
cr	ContentResolver來自調用方上下文的內容解析器。將通知附加到此解析器的偵聽器。
uri	Uri要查看的內容URI。

setNotificationUris

加進空氣污染指數第29級

public void setNotificationUris (ContentResolver cr, 
                List<Uri> uris)

類似於setNotificationUri(android.content.ContentResolver, android.net.Uri)，但此版本允許查看多個內容URI以進行更改。

如果沒有實現這一點，這相當於調用setNotificationUri(android.content.ContentResolver, android.net.Uri)中的第一個URIuris.

調用此命令將重寫以前對setNotificationUri(android.content.ContentResolver, android.net.Uri).

 

參數
cr	ContentResolver來自調用方上下文的內容解析器。將通知附加到此解析器的偵聽器。這個值絕不能是null.
uris	List要觀看的內容URI。這個值絕不能是null.

非寄存器內容觀察者

加進API一級

public abstract void unregisterContentObserver (ContentObserver observer)

註銷以前在此遊標中註冊的觀察者。registerContentObserver(ContentObserver).

 

參數
observer	ContentObserver要註銷的對象。

另見：

• registerContentObserver(ContentObserver)

取消註冊數據設置觀察者

加進API一級

public abstract void unregisterDataSetObserver (DataSetObserver observer)

註銷以前在此遊標中註冊的觀察者。registerContentObserver(ContentObserver).

 

參數
observer	DataSetObserver要註銷的對象。

另見：

• registerDataSetObserver(DataSetObserver)