fungsi getsockopt (winsock.h)

Fungsi getsockopt mengambil opsi soket.

Sintaks

int getsockopt(
  [in]      SOCKET s,
  [in]      int    level,
  [in]      int    optname,
  [out]     char   *optval,
  [in, out] int    *optlen
);

Parameter

[in] s

Deskriptor yang mengidentifikasi soket.

[in] level

Tingkat di mana opsi ditentukan. Contoh: SOL_SOCKET.

[in] optname

Opsi soket tempat nilai akan diambil. Contoh: SO_ACCEPTCONN. Nilai optname harus merupakan opsi soket yang ditentukan dalam tingkat yang ditentukan, atau perilaku tidak terdefinisi.

[out] optval

Penunjuk ke buffer tempat nilai untuk opsi yang diminta akan dikembalikan.

[in, out] optlen

Penunjuk ke ukuran, dalam byte, dari buffer optval .

Mengembalikan nilai

Jika tidak ada kesalahan yang terjadi, getsockopt mengembalikan nol. Jika tidak, nilai SOCKET_ERROR dikembalikan, dan kode kesalahan tertentu dapat diambil dengan memanggil WSAGetLastError.

Keterangan

Fungsi getsockopt mengambil nilai saat ini untuk opsi soket yang terkait dengan soket jenis apa pun, dalam status apa pun, dan menyimpan hasilnya dalam optval. Opsi dapat ada di beberapa tingkat protokol, tetapi selalu ada di tingkat soket paling atas. Opsi memengaruhi operasi soket, seperti perutean paket dan transfer data OOB.

Nilai yang terkait dengan opsi yang dipilih dikembalikan dalam optval buffer. Bilangan bulat yang diarahkan oleh optlen awalnya harus berisi ukuran buffer ini; saat dikembalikan, itu akan diatur ke ukuran nilai yang dikembalikan. Untuk SO_LINGER, ini akan menjadi ukuran struktur LINGER . Untuk sebagian besar opsi lainnya, itu akan menjadi ukuran bilangan bulat.

Aplikasi bertanggung jawab untuk mengalokasikan ruang memori apa pun yang diarahkan ke secara langsung atau tidak langsung oleh salah satu parameter yang ditentukannya.

Jika opsi tidak pernah diatur dengan setsockopt, maka getsockopt mengembalikan nilai default untuk opsi tersebut.

Opsi berikut didukung untuk getsockopt. Kolom Jenis mengidentifikasi jenis data yang ditangani berdasarkan optval.

Untuk informasi selengkapnya tentang opsi soket, lihat Opsi Soket.

Tabel nilai berikut untuk parameter optname valid saat parameter tingkat diatur ke SOL_SOCKET.

Tingkat = IPPROTO_TCP

Lihat TCP_NODELAY dalam opsi soket IPPROTO_TCP. Lihat juga topik tersebut untuk informasi yang lebih lengkap dan terperinci tentang opsi soket untuk tingkat = IPPROTO_TCP.  

Tabel nilai berikut untuk parameter optname valid saat parameter tingkat diatur ke NSPROTO_IPX.

Tabel berikut mencantumkan nilai untuk optname yang mewakili opsi soket BSD yang tidak didukung oleh fungsi getsockopt .

Memanggil getsockopt dengan opsi yang tidak didukung akan mengakibatkan kode kesalahan WSAENOPROTOOPT dikembalikan dari WSAGetLastError.

Informasi lebih rinci tentang beberapa opsi soket untuk parameter optname yang didukung oleh fungsi getsockopt tercantum di bawah ini.

SO_CONNECT_TIME

Opsi ini mengembalikan jumlah detik soket yang telah tersambung. Opsi ini hanya berlaku untuk protokol berorientasi koneksi.

Opsi SO_CONNECT_TIME dapat digunakan dengan fungsi getsockopt untuk memeriksa apakah koneksi telah dibuat. Opsi ini juga dapat digunakan saat panggilan fungsi ConnectEx sedang berlangsung. Jika koneksi dibuat, opsi SO_CONNECT_TIME dapat menentukan berapa lama koneksi telah dibuat. Jika soket tidak tersambung, getsockopt akan mengembalikan SOCKET_ERROR. Memeriksa koneksi seperti ini diperlukan untuk melihat apakah koneksi yang telah dibuat untuk sementara waktu, tanpa mengirim data apa pun. Disarankan agar aplikasi menghentikan koneksi ini.

SO_DEBUG

Catatan Penyedia layanan Windows Sockets didorong (tetapi tidak diperlukan) untuk menyediakan informasi debug output jika opsi SO_DEBUG diatur oleh aplikasi. Mekanisme untuk menghasilkan informasi debug dan formulir yang diperlukan berada di luar lingkup dokumen ini.

 

SO_ERROR

Opsi SO_ERROR mengembalikan dan mengatur ulang kode kesalahan berbasis per soket, yang berbeda dari kode kesalahan berbasis per utas yang ditangani menggunakan panggilan fungsi WSAGetLastError dan WSASetLastError . Panggilan yang berhasil menggunakan soket tidak mengatur ulang kode kesalahan berbasis soket yang dikembalikan oleh opsi SO_ERROR.

SO_EXCLUSIVEADDRUSE

Mencegah soket lain mengikat ke alamat dan port yang sama. Opsi ini harus diatur sebelum memanggil fungsi ikatan . Lihat referensi SO_EXCLUSIVEADDRUSE untuk informasi selengkapnya.

SO_GROUP_ID

Catatan Opsi ini dicadangkan. Opsi ini juga eksklusif untuk getsockopt; nilainya harus NULL.

 

SO_GROUP_PRIORITY

Opsi ini dicadangkan. Prioritas grup menunjukkan prioritas soket yang ditentukan relatif terhadap soket lain dalam grup soket. Nilai adalah bilangan bulat nonnegatif, dengan nol yang sesuai dengan prioritas tertinggi. Nilai prioritas mewakili petunjuk kepada penyedia layanan yang mendasar tentang bagaimana sumber daya yang berpotensi langka harus dialokasikan. Misalnya, setiap kali dua soket atau lebih siap untuk mengirimkan data, soket prioritas tertinggi (nilai terendah untuk SO_GROUP_PRIORITY) harus dilayankan terlebih dahulu, dengan sisanya dilayanakan sesuai dengan prioritas relatif mereka.

Kode kesalahan WSAENOPROTOOPT ditunjukkan untuk soket nongroup atau untuk penyedia layanan yang tidak mendukung soket grup.

SO_KEEPALIVE

Aplikasi dapat meminta agar penyedia layanan TCP/IP mengaktifkan penggunaan paket tetap aktif pada koneksi TCP dengan mengaktifkan opsi soket SO_KEEPALIVE. Opsi ini meminta nilai opsi tetap hidup saat ini pada soket. Penyedia Windows Sockets tidak perlu mendukung penggunaan tetap hidup: jika ya, semantik yang tepat bersifat spesifik implementasi tetapi harus sesuai dengan bagian 4.2.3.6 tentang Persyaratan untuk Host Internet—Lapisan Komunikasi yang ditentukan dalam RFC 1122 tersedia di situs web IETF. Jika koneksi terputus sebagai akibat dari tetap hidup, kode kesalahan WSAENETRESET dikembalikan ke panggilan apa pun yang sedang berlangsung di soket, dan panggilan berikutnya akan gagal dengan WSAENOTCONN. SO_KEEPALIVE tidak didukung pada soket ATM, dan permintaan untuk mengaktifkan penggunaan paket tetap hidup pada soket ATM mengalihkan kesalahan yang dikembalikan oleh soket.

SO_LINGER

SO_LINGER mengontrol tindakan yang diambil saat data yang tidak dikirim diantrekan pada soket dan closesocket dilakukan. Lihat closesocket untuk deskripsi cara pengaturan SO_LINGER memengaruhi semantik closesocket. Aplikasi mendapatkan perilaku saat ini dengan mengambil struktur LINGER (ditujukkan oleh parameter optval ).

SO_MAX_MSG_SIZE

Ini adalah opsi soket get-only yang menunjukkan ukuran keluar maksimum (kirim) pesan untuk jenis soket berorientasi pesan (misalnya, SOCK_DGRAM) seperti yang diterapkan oleh penyedia layanan tertentu. Ini tidak memiliki arti untuk soket berorientasi aliran byte. Tidak ada ketentuan untuk mengetahui ukuran pesan masuk maksimum.

SO_PROTOCOL_INFO

Ini adalah opsi get-only yang memasok struktur WSAPROTOCOL_INFO yang terkait dengan soket ini. Lihat WSAEnumProtocols untuk informasi selengkapnya tentang struktur ini.

SO_SNDBUF

Ketika implementasi Windows Sockets mendukung opsi SO_RCVBUF dan SO_SNDBUF, aplikasi dapat meminta ukuran buffer yang berbeda (lebih besar atau lebih kecil). Panggilan ke setsockopt dapat berhasil bahkan jika implementasi tidak memberikan seluruh jumlah yang diminta. Aplikasi harus memanggil fungsi ini dengan opsi yang sama untuk memeriksa ukuran buffer yang benar-benar disediakan.

SO_REUSEADDR

Secara default, soket tidak dapat diikat (lihat ikatan) ke alamat lokal yang sudah digunakan. Namun, terkadang, perlu untuk menggunakan kembali alamat dengan cara ini. Karena setiap koneksi diidentifikasi secara unik oleh kombinasi alamat lokal dan jarak jauh, tidak ada masalah dengan memiliki dua soket yang terikat ke alamat lokal yang sama selama alamat jarak jauh berbeda. Untuk memberi tahu penyedia Soket Windows bahwa ikatan pada soket tidak boleh dilarang karena alamat yang diinginkan sudah digunakan oleh soket lain, aplikasi harus mengatur opsi soket SO_REUSEADDR untuk soket sebelum mengeluarkan ikatan. Perhatikan bahwa opsi hanya ditafsirkan pada saat pengikatan: oleh karena itu tidak perlu (tetapi tidak berbahaya) untuk mengatur opsi pada soket yang tidak terikat ke alamat yang ada, dan mengatur atau mengatur ulang opsi setelah ikatan tidak berpengaruh pada soket ini atau soket lainnya. SO_REUSEADDR tidak berlaku untuk soket ATM, dan meskipun permintaan untuk menggunakan kembali dan alamat tidak mengakibatkan kesalahan, mereka tidak berpengaruh ketika soket ATM sedang digunakan.

PVD_CONFIG

Opsi ini mengambil objek struktur data buram dari penyedia layanan yang terkait dengan soket. Objek ini menyimpan informasi konfigurasi penyedia layanan saat ini. Format yang tepat dari struktur data ini khusus untuk penyedia layanan.

TCP_NODELAY

Opsi TCP_NODELAY khusus untuk penyedia layanan TCP/IP. Algoritma Nagle dinonaktifkan jika opsi TCP_NODELAY diaktifkan (dan sebaliknya). Algoritma Nagle (dijelaskan dalam RFC 896) sangat efektif dalam mengurangi jumlah paket kecil yang dikirim oleh host. Proses ini melibatkan buffering mengirim data ketika ada data yang tidak diakui yang sudah ada dalam penerbangan atau buffering mengirim data hingga paket ukuran penuh dapat dikirim. Sangat disarankan bahwa implementasi Windows Sockets memungkinkan Algoritma Nagle secara default karena, untuk sebagian besar protokol aplikasi, Nagle Algoritma dapat memberikan peningkatan performa yang signifikan. Namun, untuk beberapa aplikasi algoritma ini dapat menghambat performa, dan setsockopt dengan opsi yang sama dapat digunakan untuk menonaktifkannya. Ini adalah aplikasi di mana banyak pesan kecil dikirim, dan penundaan waktu antara pesan dipertahankan.

Contoh Kode

#include <stdio.h>
#include "winsock2.h"
#include <windows.h>

void main() {

  //---------------------------------------
  // Declare variables
  WSADATA wsaData;
  SOCKET ListenSocket;
  sockaddr_in service;

  //---------------------------------------
  // Initialize Winsock
  int iResult = WSAStartup( MAKEWORD(2,2), &wsaData );
  if( iResult != NO_ERROR )
    printf("Error at WSAStartup\n");

  //---------------------------------------
  // Create a listening socket
  ListenSocket = socket( AF_INET, SOCK_STREAM, IPPROTO_TCP );
  if (ListenSocket == INVALID_SOCKET) {
    printf("Error at socket()\n");
    WSACleanup();
    return;
  }

  //---------------------------------------
  // Bind the socket to the local IP address
  // and port 27015
  hostent* thisHost;
  char* ip;
  u_short port;
  port = 27015;
  thisHost = gethostbyname("");
  ip = inet_ntoa (*(struct in_addr *)*thisHost->h_addr_list);

  service.sin_family = AF_INET;
  service.sin_addr.s_addr = inet_addr(ip);
  service.sin_port = htons(port);
 
  if ( bind( ListenSocket,(SOCKADDR*) &service, sizeof(service) )  == SOCKET_ERROR ) {
    printf("bind failed\n");
    closesocket(ListenSocket);
    return;
  }

  //---------------------------------------
  // Initialize variables and call getsockopt. 
  // The SO_ACCEPTCONN parameter is a socket option 
  // that tells the function to check whether the 
  // socket has been put in listening mode or not. 
  // The various socket options return different
  // information about the socket. This call should
  // return 0 to the optVal parameter, since the socket
  // is not in listening mode.
  int optVal;
  int optLen = sizeof(int);

  if (getsockopt(ListenSocket, 
    SOL_SOCKET, 
    SO_ACCEPTCONN, 
    (char*)&optVal, 
    &optLen) != SOCKET_ERROR)
    printf("SockOpt Value: %ld\n", optVal);

  //---------------------------------------
  // Put the listening socket in listening mode.
  if (listen( ListenSocket, 100 ) == SOCKET_ERROR) {
    printf("error listening\n");
  } 

  //---------------------------------------
  // Call getsockopt again to verify that 
  // the socket is in listening mode.
  if (getsockopt(ListenSocket, 
    SOL_SOCKET, 
    SO_ACCEPTCONN, 
    (char*)&optVal, 
    &optLen) != SOCKET_ERROR)
    printf("SockOpt Value: %ld\n", optVal);

  WSACleanup();
  return;
}

Catatan untuk Soket IrDA

• File header Af_irda.h harus disertakan secara eksplisit.
• Windows mengembalikan WSAENETDOWN untuk menunjukkan driver transceiver yang mendasar gagal diinisialisasi dengan tumpukan protokol IrDA.
• IrDA mendukung beberapa opsi soket khusus:

  Nilai	Jenis	Makna
  IRLMP_ENUMDEVICES	*DEVICELIST	Menjelaskan perangkat dalam rentang.
  IRLMP_IAS_QUERY	*IAS_QUERY	Ambil atribut IAS.

   

Sebelum koneksi soket IrDA dapat dimulai, alamat perangkat harus diperoleh dengan melakukan panggilan fungsi getsockopt(,,IRLMP_ENUMDEVICES,,), yang mengembalikan daftar semua perangkat IrDA yang tersedia. Alamat perangkat yang dikembalikan dari panggilan fungsi disalin ke dalam struktur SOCKADDR_IRDA , yang pada gilirannya digunakan oleh panggilan berikutnya ke panggilan fungsi sambungkan .

Penemuan dapat dilakukan dengan dua cara:

1. Pertama, melakukan panggilan fungsi getsockopt dengan opsi IRLMP_ENUMDEVICES menyebabkan satu penemuan dijalankan pada setiap adaptor diam. Daftar perangkat yang ditemukan dan perangkat yang di-cache (pada adaptor aktif) segera dikembalikan.

   Kode berikut menunjukkan pendekatan ini.

   #include <winsock2.h>
   #include <ws2tcpip.h>
   #include <af_irda.h>
   #include <stdio.h>
   #include <windows.h>
   
   // link with Ws2_32.lib
   
   int __cdecl main()
   {
   
       //-----------------------------------------
       // Declare and initialize variables
       WSADATA wsaData;
   
       int iResult;
       int i;
       DWORD dwError;
   
       SOCKET Sock = INVALID_SOCKET;
   
   #define DEVICE_LIST_LEN    10
   
   
       SOCKADDR_IRDA DestSockAddr = { AF_IRDA, 0, 0, 0, 0, "SampleIrDAService" };
   
       unsigned char DevListBuff[sizeof (DEVICELIST) -
                                 sizeof (IRDA_DEVICE_INFO) +
                                 (sizeof (IRDA_DEVICE_INFO) * DEVICE_LIST_LEN)];
   
       int DevListLen = sizeof (DevListBuff);
       PDEVICELIST pDevList;
   
       pDevList = (PDEVICELIST) & DevListBuff;
   
       // Initialize Winsock
       iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
       if (iResult != 0) {
           printf("WSAStartup failed: %d\n", iResult);
           return 1;
       }
   
       Sock = socket(AF_IRDA, SOCK_STREAM, 0);
       if (Sock == INVALID_SOCKET) {
           dwError = WSAGetLastError();
           printf
               ("socket failed trying to create an AF_IRDA socket with error %d\n",
                dwError);
   
           if (dwError == WSAEAFNOSUPPORT) {
               printf("Check that the local computer has an infrared device\n");
               printf
                   ("and a device driver is installed for the infrared device\n");
           }
           WSACleanup();
           return 1;
       }
       // Sock is not in connected state
       iResult = getsockopt(Sock, SOL_IRLMP, IRLMP_ENUMDEVICES,
                            (char *) pDevList, &DevListLen);
       if (iResult == SOCKET_ERROR) {
           printf("getsockopt failed with error %d\n", WSAGetLastError());
           WSACleanup();
           return 1;
       }
   
       if (pDevList->numDevice == 0) {
           // no devices discovered or cached
           // not a bad idea to run a couple of times
           printf("No IRDA devices were discovered or cached\n");
       } else {
           // one per discovered device
           for (i = 0; i < (int) pDevList->numDevice; i++) {
               // typedef struct _IRDA_DEVICE_INFO
               // {
               //     u_char    irdaDeviceID[4];
               //     char      irdaDeviceName[22];
               //     u_char    irdaDeviceHints1;
               //     u_char    irdaDeviceHints2;
               //     u_char    irdaCharSet;
               // } _IRDA_DEVICE_INFO;
   
               // pDevList->Device[i]. see _IRDA_DEVICE_INFO for fields
               // display the device names and let the user select one
           }
       }
   
       // assume the user selected the first device [0]
       memcpy(&DestSockAddr.irdaDeviceID[0], &pDevList->Device[0].irdaDeviceID[0],
              4);
   
       iResult = connect(Sock, (const struct sockaddr *) &DestSockAddr,
                         sizeof (SOCKADDR_IRDA));
       if (iResult == SOCKET_ERROR) {
           printf("connect failed with error %d\n", WSAGetLastError());
       } else
           printf("connect to first IRDA device was successful\n");
   
       WSACleanup();
       return 0;
   }
   
   

2. Pendekatan kedua untuk melakukan penemuan alamat perangkat IrDA adalah melakukan penemuan malas; dalam pendekatan ini, aplikasi tidak diberi tahu sampai daftar perangkat yang ditemukan berubah dari penemuan terakhir yang dijalankan oleh tumpukan.

Struktur IAS_QUERY yang diperlihatkan dalam kolom Jenis dalam tabel sebelumnya digunakan untuk mengambil satu atribut dari satu kelas dari database IAS perangkat serekan. Aplikasi menentukan perangkat dan kelas untuk dikueri serta atribut dan jenis atribut. Perhatikan bahwa perangkat akan diperoleh sebelumnya dengan panggilan ke getsockopt(IRLMP_ENUMDEVICES). Diharapkan bahwa aplikasi mengalokasikan buffer, dengan ukuran yang diperlukan, untuk parameter yang dikembalikan.

Banyak opsi soket tingkat tidak bermakna bagi IrDA; hanya SO_LINGER dan SO_DONTLINGER yang didukung secara khusus.

Windows Phone 8: Fungsi ini didukung untuk aplikasi Windows Phone Store di Windows Phone 8 dan yang lebih baru.

Windows 8.1 dan Windows Server 2012 R2: Fungsi ini didukung untuk aplikasi Windows Store di Windows 8.1, Windows Server 2012 R2, dan yang lebih baru.

Persyaratan

Lihat juga

Opsi Soket IPPROTO_IP

Opsi Soket IPPROTO_IPV6

Opsi Soket IPPROTO_RM

Opsi Soket IPPROTO_TCP

Opsi Soket IPPROTO_UDP

Opsi Soket NSPROTO_IPX

Opsi Soket SOL_APPLETALK

Opsi Soket SOL_IRLMP

Opsi Soket SOL_SOCKET

Opsi Soket

WSAAsyncSelect

WSAConnect

WSAGetLastError

WSAIoctl

WSASetLastError

Fungsi Winsock

ioctlsocket

recv

setsockopt

soket