Bagikan melalui

struktur RPC_CALL_ATTRIBUTES_V1_A (rpcasync.h)

  • Artikel

Struktur RPC_CALL_ATTRIBUTES_V1 menyediakan parameter untuk fungsi RpcServerInqCallAttributes . Diimplementasikan dalam versi ANSI dan UNICODE untuk sistem operasi Windows XP dan Windows Server 2003.

Sintaks

typedef struct tagRPC_CALL_ATTRIBUTES_V1_A {
  unsigned int  Version;
  unsigned long Flags;
  unsigned long ServerPrincipalNameBufferLength;
  unsigned char *ServerPrincipalName;
  unsigned long ClientPrincipalNameBufferLength;
  unsigned char *ClientPrincipalName;
  unsigned long AuthenticationLevel;
  unsigned long AuthenticationService;
  BOOL          NullSession;
} RPC_CALL_ATTRIBUTES_V1_A;

Anggota

Version

Versi fungsi RpcServerInqCallAttributes yang digunakan oleh aplikasi panggilan. Lihat Keterangan.

Flags

Bitmask menentukan bendera yang valid untuk meminta RPC_QUERY_SERVER_PRINCIPAL_NAME atau RPC_QUERY_CLIENT_PRINCIPAL_NAME. Lihat Keterangan.

ServerPrincipalNameBufferLength

Panjang ServerPrincipalName, dalam byte. Jika tidak mencukupi, ServerPrincipalName tidak berubah, dan ServerPrincipalNameBufferLength menunjukkan panjang buffer yang diperlukan termasuk karakter NULL yang mengakhiri, dan ERROR_MORE_DATA dikembalikan. Jika ServerPrincipalNameBufferLength lebih panjang dari yang diperlukan, setelah dikembalikan, panjang aktual yang digunakan, dalam byte, termasuk karakter NULL yang mengakhiri. Lihat Keterangan.

Jika urutan protokol tidak mendukung pengambilan nama utama server, ServerPrincipalNameBufferLength diatur ke nol saat dikembalikan, dan buffer yang ditujukan oleh ServerPrincipalName tidak dimodifikasi. Windows XP: Hanya grup urutan protokol ncacn_* yang mendukung pengambilan nama utama server.

Jika bendera RPC_QUERY_SERVER_PRINCIPAL_NAME tidak ditentukan, ServerPrincipalNameBufferLength diabaikan. Jika ServerPrincipalNameBufferLength bukan nol dan ServerPrincipalNameadalah NULL, ERROR_INVALID_PARAMETER dikembalikan.

ServerPrincipalName

Arahkan ke nama utama server, jika diminta di Bendera dan didukung oleh urutan protokol. Setelah nilai pengembalian selain RPC_S_OK atau ERROR_MORE_DATA, konten ServerPrincipalName tidak ditentukan dan mungkin telah dimodifikasi oleh RPC.

ClientPrincipalNameBufferLength

Panjang buffer yang diacu oleh ClientPrincipalName, dalam byte. Jika tidak mencukupi, ClientPrincipalName tidak berubah, dan ClientPrincipalNameBufferLength menunjukkan panjang buffer yang diperlukan termasuk karakter NULL yang mengakhiri, dan ERROR_MORE_DATA dikembalikan. Jika ClientPrincipalNameBufferLength lebih panjang dari yang diperlukan, setelah dikembalikan, panjang aktual yang digunakan, dalam byte, termasuk karakter NULL yang mengakhiri.

Jika urutan protokol tidak mendukung pengambilan nama utama klien, ClientPrincipalNameBufferLength diatur ke nol saat dikembalikan, dan buffer yang ditujukan oleh ClientPrincipalName tidak dimodifikasi. Windows XP: Hanya urutan protokol ncalrpc yang mendukung pengambilan nama utama klien.

Jika bendera RPC_QUERY_CLIENT_PRINCIPAL_NAME tidak ditentukan, ClientPrincipalNameBufferLength diabaikan. Jika ClientPrincipalNameBufferLength bukan nol dan ClientPrincipalNameadalah NULL, ERROR_INVALID_PARAMETER dikembalikan.

ClientPrincipalName

Arahkan ke nama utama klien, jika diminta di anggota Bendera dan didukung oleh urutan protokol. Setelah nilai pengembalian selain RPC_S_OK atau ERROR_MORE_DATA, konten ClientPrincipalName tidak ditentukan dan mungkin telah dimodifikasi oleh RPC.

AuthenticationLevel

Tingkat autentikasi untuk panggilan. Lihat Konstanta Tingkat Autentikasi untuk tingkat autentikasi yang didukung oleh RPC.

AuthenticationService

Layanan autentikasi, atau penyedia keamanan, digunakan untuk melakukan panggilan prosedur jarak jauh.

NullSession

Menentukan apakah sesi Null digunakan. Zero menunjukkan panggilan tidak datang melalui sesi Null ; nilai lainnya menunjukkan sesi Null .

Keterangan

Struktur RPC_CALL_ATTRIBUTES menggunakan skema penerapan versi untuk mengaktifkan fungsi RpcServerInqCallAttributes untuk menggabungkan kemampuan baru tanpa harus memperkenalkan fungsi baru dengan pengidentifikasi akhiran. Misalnya, versi kedua RPC_CALL_ATTRIBUTES, yang diidentifikasi dengan #define sederhana di header, dapat menambahkan anggota baru untuk memfasilitasi fungsionalitas baru yang dibangun ke dalam versi mendatang dari fungsi RpcServerInqCallAttributes , tanpa harus merilis fungsi alternatif yang sesuai.

Anggota Versi menunjukkan versi struktur RPC_CALL_ATTRIBUTES (saat ini RPC_CALL_ATTRIBUTES_V1 atau RPC_CALL_ATTRIBUTES_V2) yang digunakan oleh aplikasi panggilan. Identifikasi ini memungkinkan run time RPC untuk memberikan kompatibilitas mundur untuk aplikasi yang tidak menggunakan versi struktur terbaru.

Menentukan RPC_QUERY_SERVER_PRINCIPAL_NAME di anggota Bendera mengarahkan RpcServerInqCallAttributes untuk mengembalikan nama utama server di ServerPrincipalName. Jika RPC_QUERY_SERVER_PRINCIPAL_NAME tidak ditentukan, RpcServerInqCallAttributes tidak mengubah pointer yang diteruskan di ServerPrincipalName dan tidak menyimpan apa pun di lokasi memori tersebut. Menentukan RPC_QUERY_CLIENT_PRINCIPAL_NAME di anggota Flags mengarahkan RpcServerInqCallAttributes untuk mengembalikan nama utama klien di ClientPrincipalName. Jika RPC_QUERY_CLIENT_PRINCIPAL_NAME tidak ditentukan, RpcServerInqCallAttributes tidak memodifikasi pointer yang diteruskan di ClientPrincipalName dan tidak menyimpan apa pun di lokasi memori tersebut.

Mekanisme pemrosesan terbaik ketika nama utama klien dan server sedang diambil adalah menyimpan panjang ClientPrincipalNameBufferLength dan ServerPrincipalNameBufferLength, dan jika ERROR_MORE_DATA dikembalikan, bandingkan panjang tersimpan dengan panjang yang dikembalikan dalam anggota tersebut. Anggota dengan nilai tersimpan yang lebih kecil dari atau sama dengan nilai yang dikembalikan telah berhasil dikembalikan, menunjukkan bahwa anggota lain memiliki buffer yang tidak mencukuum. Dalam panggilan berikutnya, hilangkan bendera untuk nama utama yang berhasil dikembalikan; ini menghindari pemrosesan yang terkait dengan pengambilan lain dan salinan nama utama yang berhasil dikembalikan.

Struktur RPC_CALL_ATTRIBUTES_V1 biasanya dipanggil dengan dua cara:

  • Pendekatan pertama: nol ditentukan untuk anggota fungsi ServerPrincipalNameBufferLength atau ClientPrincipalNameBufferLength pada panggilan fungsi RpcServerInqCallAttributes pertama untuk mengambil panjang buffer yang diperlukan, atau untuk menentukan apakah protokol mendukung pengembalian nama utama. Setelah mengambil panjang buffer yang diperlukan, buffer dialokasikan dengan panjang yang diperlukan dan panggilan kedua dilakukan untuk mendapatkan panjang buffer yang sebenarnya.
  • Pendekatan kedua: pemanggil dimulai dengan buffer yang wajar, sering dialokasikan pada tumpukan, dan jika ERROR_MORE_DATA dikembalikan, buffer dengan panjang yang diperlukan dialokasikan dan fungsi RpcServerInqCallAttributes dipanggil lagi.
Metode kedua menawarkan performa terbaik dalam banyak kasus, karena pemanggil tidak perlu melakukan alokasi memori.

Contoh

RPC_CALL_ATTRIBUTES CallAttributes;  // this maps to RPC_CALL_ATTRIBUTES_V1

memset(&CallAttributes, 0, sizeof(CallAttributes));
CallAttributes.Version = RPC_CALL_ATTRIBUTES_VERSION;    // maps to 1
CallAttributes.Flags = ;//....
Status = RpcServerInqCallAttributes(0, &CallAttributes);

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2003 [hanya aplikasi desktop]
Header rpcasync.h (termasuk Rpc.h)

Lihat juga

Konstanta Tingkat Autentikasi

RpcServerInqCallAttributes