檢視原始碼 儀器功能定義

儀器功能定義 章節描述了代理程式在不同時間呼叫的使用者定義函式。

變數儀器

對於純量變數，必須定義函式 f(Operation, ...)。

Operation 可以是 new、delete、get、is_set_ok、set 或 undo。

如果發生錯誤，所有儀器函式都可能傳回 SNMPv1 或 SNMPv2 錯誤碼。如果它傳回 SNMPv2 程式碼，則在傳送至 SNMPv1 管理器之前會轉換為 SNMPv1 程式碼。建議所有儀器函式都使用 SNMPv2 錯誤碼，因為它們提供更多詳細資訊。有關錯誤碼轉換的說明，請參閱附錄 A。

f(new [, ExtraArgs])

當 MIB 載入到代理程式時，會針對 MIB 中的每個變數呼叫函式 f(new [, ExtraArgs])。這使得可以執行必要的初始化。

此函式為選用。傳回值會被捨棄。

f(delete [, ExtraArgs])

當 MIB 從代理程式卸載時，會針對 MIB 中的每個物件呼叫函式 f(delete [, ExtraArgs])。這使得可以執行必要的清理。

此函式為選用。傳回值會被捨棄。

f(get [, ExtraArgs])

當 get 請求或 get-next 請求引用變數時，會呼叫函式 f(get [, ExtraArgs])。

此函式為必要。

有效的傳回值

  • {value, Value}。Value 必須具有正確的類型、長度，並且在範圍內，否則會在回應 PDU 中傳回 genErr。如果物件是列舉整數，則可以使用符號列舉值作為原子。如果物件的類型為 BITS，則傳回值應為整數或已設定的位元列表。
  • {noValue, noSuchName} (SNMPv1)

  • {noValue, noSuchObject | noSuchInstance} (SNMPv2)

  • genErr。如果發生錯誤則使用。請注意，這應該是內部處理錯誤，例如，由某處的程式設計錯誤導致。如果變數不存在，請使用 {noValue, noSuchName} 或 {noValue, noSuchInstance}。

f(is_set_ok, NewValue [, ExtraArgs])

在 set 請求處理的第一階段中會呼叫函式 f(is_set_ok, NewValue [, ExtraArgs])，以便可以檢查新值是否存在不一致之處。

保證 NewValue 具有正確的類型、長度，並且在 MIB 中指定的範圍內。如果物件是列舉整數或類型為 BITS，則使用整數值。

此函式為選用。

如果呼叫此函式，則會再次呼叫此函式，第一個引數為 undo 或 set。

有效的傳回值

  • noError

  • badValue | noSuchName | genErr (SNMPv1)

  • noAccess | noCreation | inconsistentValue | resourceUnavailable | inconsistentName | genErr (SNMPv2)

f(undo, NewValue [, ExtraArgs])

如果發生錯誤，則會在呼叫 is_set_ok 函式之後呼叫此函式。如果針對此物件呼叫 set，則不會呼叫 undo。

保證 NewValue 具有正確的類型、長度，並且在 MIB 中指定的範圍內。如果物件是列舉整數或類型為 BITS，則使用整數值。

此函式為選用。

有效的傳回值

  • noError
  • genErr (SNMPv1)

  • undoFailed | genErr (SNMPv2)

f(set, NewValue [, ExtraArgs])

呼叫此函式以在 set 請求處理的第二階段中執行 set。只有在對應的 is_set_ok 函式存在並傳回 noError 時才會呼叫此函式。

保證 NewValue 具有正確的類型、長度，並且在 MIB 中指定的範圍內。如果物件是列舉整數或類型為 BITS，則使用整數值。

此函式為必要。

有效的傳回值

  • noError
  • genErr (SNMPv1)

  • commitFailed | undoFailed | genErr (SNMPv2)

表格儀器

對於表格，應定義 f(Operation, ...) 函式 (顯示的函式以 f 為例)。

Operation 可以是 new、delete、get、next、is_set_ok、undo 或 set。

如果發生錯誤，所有儀器函式都可能傳回 SNMPv1 或 SNMPv2 錯誤碼。如果它傳回 SNMPv2 程式碼，則在傳送至 SNMPv1 管理器之前會轉換為 SNMPv1 程式碼。建議所有儀器函式都使用 SNMPv2 錯誤碼，因為它們提供更多詳細資訊。有關錯誤碼轉換的說明，請參閱附錄 A。

f(new [, ExtraArgs])

當 MIB 載入到代理程式時，會針對 MIB 中的每個物件呼叫函式 f(new [, ExtraArgs])。這使得可以執行必要的初始化。

此函式為選用。傳回值會被捨棄。

f(delete [, ExtraArgs])

當 MIB 從代理程式卸載時，會針對 MIB 中的每個物件呼叫函式 f(delete [, ExtraArgs])。這使得可以執行任何必要的清理。

此函式為選用。傳回值會被捨棄。

f(get, RowIndex, Cols [, ExtraArgs])

當 get 請求引用表格時，會呼叫函式 f(get, RowIndex, Cols [, ExtraArgs])。

此函式為必要。

引數

  • RowIndex 是定義列索引鍵值的整數列表。RowIndex 是 OBJECT IDENTIFIER 中 Cols 整數後面的列表表示法 (整數列表)。
  • Cols 是表示欄號的整數列表。Cols 按遞增值排序，並保證是有效的欄號。

有效的傳回值

  • 一個列表，其元素數量與 Cols 列表一樣多，其中每個元素都是對應欄的值。每個元素可以是

    • {value, Value}。Value 必須具有正確的類型、長度，並且在範圍內，否則會在回應 PDU 中傳回 genErr。如果物件是列舉整數，則可以使用符號列舉值 (作為原子)。如果物件的類型為 BITS，則傳回值應為整數或已設定的位元列表。
    • {noValue, noSuchName} (SNMPv1)

    • {noValue, noSuchObject | noSuchInstance} (SNMPv2)

  • {noValue, Error}。如果列不存在，因為所有欄都具有 {noValue, Error}，則可以傳回單一元組 {noValue, Error}。這是所有元素 {noValue, Error} 的列表的簡寫。

  • genErr。如果發生錯誤則使用。請注意，這應該是內部處理錯誤，例如，由某處的程式設計錯誤導致。如果某些欄不存在，請使用 {noValue, noSuchName} 或 {noValue, noSuchInstance}。

f(get_next, RowIndex, Cols [, ExtraArgs])

當 get-next 或 get-bulk 請求引用表格時，會呼叫函式 f(get_next, RowIndex, Cols [, ExtraArgs])。

RowIndex 引數可以引用現有列或不存在的列，也可以是不指定的。 Cols 列表可以引用無法存取的欄或不存在的欄。對於 Cols 列表中的每個欄，會確定對應的下一個執行個體，並傳回其 OBJECT IDENTIFIER 的最後一部分及其值。

此函式為必要。

引數

  • RowIndex 是定義列索引鍵值的整數列表 (可能為空)。RowIndex 是 OBJECT IDENTIFIER 中 Cols 整數後面的列表表示法 (整數列表)。
  • Cols 是一個大於或等於零的整數列表，表示欄號。

有效的傳回值

  • 一個列表，其元素數量與 Cols 列表一樣多。每個元素可以是

    • {NextOid, NextValue}，其中 NextOid 是對應欄的詞彙下一個 OBJECT IDENTIFIER。這應指定為表格項目後面的 OBJECT IDENTIFIER 部分。這表示第一個整數是欄號，其餘部分是索引鍵的規格。NextValue 是此元素的值。
    • 如果此之後沒有可存取的元素，則為 endOfTable。

  • {genErr, Column}，其中 Column 表示導致錯誤的欄。Column 必須是 Cols 列表中的其中一個欄。請注意，這應該是內部處理錯誤，例如，由某處的程式設計錯誤導致。如果某些欄不存在，則必須傳回下一個可存取的元素 (或 endOfTable)。

f(is_set_ok, RowIndex, Cols [, ExtraArgs])

在 set 請求處理的第一階段中會呼叫函式 f(is_set_ok, RowIndex, Cols [, ExtraArgs])，以便可以檢查新值是否存在不一致之處。

如果呼叫此函式，則會再次呼叫此函式，第一個引數為 undo 或 set。

此函式為選用。

引數

  • RowIndex 是定義列索引鍵值的整數列表。RowIndex 是 OBJECT IDENTIFIER 中 Cols 整數後面的列表表示法 (整數列表)。
  • Cols 是 {Column, NewValue} 的列表，其中 Column 是整數，並且保證 NewValue 具有正確的類型、長度，並且在 MIB 中指定的範圍內。如果物件是列舉整數或類型為 BITS，則使用整數值。該列表按 Column (遞增) 排序，並且保證每個 Column 都是有效的欄號。

有效的傳回值

  • {noError, 0}
  • {Error, Column}，其中 Error 與變數的 is_set_ok 相同，並且 Column 表示錯誤的欄。Column 必須是 Cols 列表中的其中一個欄。

f(undo, RowIndex, Cols [, ExtraArgs])

如果發生錯誤，則在 is_set_ok 函數之後會呼叫函數 f(undo, RowIndex, Cols [, ExtraArgs])。如果針對此物件呼叫 set，則不會呼叫 undo。

此函式為選用。

引數

  • RowIndex 是定義列索引鍵值的整數列表。RowIndex 是 OBJECT IDENTIFIER 中 Cols 整數後面的列表表示法 (整數列表)。
  • Cols 是 {Column, NewValue} 的列表，其中 Column 是整數，並且保證 NewValue 具有正確的類型、長度，並且在 MIB 中指定的範圍內。如果物件是列舉整數或類型為 BITS，則使用整數值。該列表按 Column (遞增) 排序，並且保證每個 Column 都是有效的欄號。

有效的傳回值

  • {noError, 0}
  • {Error, Column}，其中 Error 與變數的 undo 相同，而 Column 表示錯誤的欄位。Column 必須是 Cols 清單中的其中一個欄位。

f(set, RowIndex, Cols [, ExtraArgs])

函數 f(set, RowIndex, Cols [, ExtraArgs]) 會被呼叫，以在設定請求處理的第二階段執行設定。只有在對應的 is_set_ok 函數不存在，或返回 {noError, 0} 時，才會呼叫此函數。

此函式為必要。

引數

  • RowIndex 是一個整數列表，定義了該列的鍵值。RowIndex 是列表表示法（整數列表），其遵循 OBJECT IDENTIFIER 中的 Cols 整數。
  • Cols 是 {Column, NewValue} 的列表，其中 Column 是整數，並且保證 NewValue 具有正確的類型、長度，並且在 MIB 中指定的範圍內。如果物件是列舉整數或類型為 BITS，則使用整數值。該列表按 Column (遞增) 排序，並且保證每個 Column 都是有效的欄號。

有效的傳回值

  • {noError, 0}
  • {Error, Column}，其中 Error 與變數的 set 相同，而 Column 表示錯誤的欄位。Column 必須是 Cols 清單中的其中一個欄位。