Protocols/OSCAR/SNAC/OSERVICE SERVICE REQUEST

From NINA Wiki
Jump to navigation Jump to search
OSCAR Protocol
IntroductionTermsClients
Basic
DatatypesFLAPSNACTLV
UUIDsErrorsTool IDs
Host Interaction
Rate LimitsMigrationMessages
Other Services
ADMINADVERTALERT
BARTBOSBUCPCHAT
CHAT_NAV
Tutorials
Sign OnBARTRendezvous
ICBMLocateBuddies
Foodgroups
OSERVICE (0x0001)
LOCATE (0x0002)
BUDDY (0x0003)
ICBM (0x0004)
ADVERT (0x0005)
INVITE (0x0006)
ADMIN (0x0007)
POPUP (0x0008)
PD (0x0009)
USER_LOOKUP (0x000A)
STATS (0x000B)
TRANSLATE (0x000C)
CHAT_NAV (0x000D)
CHAT (0x000E)
ODIR (0x000F)
BART (0x0010)
FEEDBAG (0x0013)
ICQ (0x0015)
BUCP (0x0017)
ALERT (0x0018)
PLUGIN (0x0022)
UNNAMED_FG_24 (0x0024)
MDIR (0x0025)
ARS (0x044A)
ID Origin Name Foodgroup Service Status Version
0x0001, 0x0004 Client OSERVICE__SERVICE_REQUEST OSERVICE BOS Active 4.0

This SNAC requests that the specified service (foodgroup) be provided to it in a way further specified by qualifying parameters.

Introduction

The server will either reject the request via an error reply or accept it and reply with a OSERVICE_SERVICE_RESPONSE. Note that this is a request for new service; this is not like a migration case where the current FLAP connection might be dropped.

Services

There are other backend hosts that a client may need to connect to for more advanced commands. To connect to a secondary host, a client sends up a SERVICE_REQUEST and receives a OSERVICE_SERVICE_RESPONSE back with the connection information. The secondary servers include:

Service ID Note
ADMIN 0x0007 Account administration service
ADVERT 0x0005 Advertising service
ALERT 0x0018 For notices such as new mail
BART 0x0010 For downloading Buddy Art
BUCP 0x0017 For authorization, registration, and account deletion
CHAT_NAV 0x000D Chat navigation service
CHAT 0x000E Chat service

SNAC Header

Foodgroup uint16 (word) 00 01
Subgroup uint16 (word) 00 04
Flags uint16 (word) 00 00
Request ID uint32 (dword) xx xx xx xx

SNAC Data

Name Type Note
foodgroup uint16 (word) Group being requested
qualifyingParameters Rest of SNAC array of TLV [Class: OSERVICE__SERVICE_REQUEST_TAGS] Modifiers for the request, such as a TLS request

TLV Class: OSERVICE__SERVICE_REQUEST_TAGS

These are the tags the client uses to control what type of service request it wants.

Name Tag Type Notes
OSERVICE__TLV_TAGS_SSL_USE_SSL 0x8C empty No value; if present use SSL

From Aleksandr Shutko: SNAC(01,04) OSERVICE__SERVICE_REQUEST


Used when client want to use new service. Server should respond with SNAC(01,05), that contain BOS server address and authorization cookie.

 00 01   word   SNAC family
 00 05   word   SNAC subtype
 00 00   word   SNAC flags
 xx xx xx xx   dword   SNAC request-id
 xx xx   word   requested service (family) id
 May contain TLV sequence here.


Example SNAC dumps with flap header:


  2A 02 3E 02 00 0C 00 01  00 04 00 00 00 00 00 05 *.>.............
  00 0D                                            ..


From Aleksandr Shutko: Service request sequence example dump

 Service request sequence example dump   

 

  // client sends service 0x10 request on BOS connection
  2A 02 12 AB 00 0C 00 01  00 04 00 00 5D 0E 00 04  *...........]...
  00 10                                             ..

  // server reply with server ip 64.12.31.136 & auth cookie
  2A 02 26 06 01 2C 00 01  00 05 80 00 5D 0E 00 04  *.&..,......]...
  00 06 00 01 00 02 00 04  00 0D 00 02 00 10 00 05  ................
  00 0C 36 34 2E 31 32 2E  33 31 2E 31 33 36 00 06  ..64.12.31.136..
  01 00 7B F3 F0 F3 A4 A5  6C 67 C5 DF 4B 78 4C 43  ..{.....lg..KxLC
  C7 6C 3D 44 32 8D 96 82  DA 6A 41 7E 83 27 F4 D9  .l=D2....jA~.'..
  B8 A5 83 6B 54 95 1B 91  B9 FE 6D A3 B6 86 FC 21  ...kT.....m....!
  C7 F0 53 C1 A5 38 D6 07  D7 CA AA 7F 3E B6 FE D9  ..S..8......>...
  AD D7 AE 31 1B 6A A4 52  40 23 38 25 98 40 73 96  ...1.j.R@#8%.@s.
  E7 17 B8 31 C3 44 E8 98  15 1F DD E0 5C 31 48 7B  ...1.D......\1H{
  7D E5 92 E8 35 14 C4 1E  1C 9C 4F FB F8 55 76 B1  }...5.....O..Uv.
  68 DB CE 72 06 43 1A 77  78 12 83 AD EB 27 D3 2D  h..r.C.wx....'.-
  2A 69 47 A5 FC DE C5 89  16 2E 74 52 BB 5C 6B BE  *iG.......tR.\k.
  66 86 AB 83 3E C3 7C E8  24 C5 16 CE 4A 34 13 95  f...>.|.$...J4..
  1B E4 56 35 EA 18 FC D5  F7 24 0F 64 6A E6 D4 5D  ..V5.....$.dj..]
  BF 14 57 CE 4B 1D 7E CF  8F FD 1F CA 35 FA 29 97  ..W.K.~.....5.).
  21 DC F7 1C 1A 36 24 CD  CC 5F 05 9C 44 A6 23 DF  !....6$.._..D.#.
  BB 09 B2 36 17 36 91 26  0B 84 75 EA D2 FC BD 70  ...6.6.&..u....p
  0F C6 6C 67 D0 64 99 82  A4 C2 00 10 D8 8C FF D9  ..lg.d..........
  71 9F 50 25 8A 2A BD C6  5E 27 8B 33 BE 81 21 D1  q.P%.*..^'.3..!.
  2B 4B                                             +K

  -------------------------------------------------------------------
  // Then client makes tcp connection to 64.12.31.136

  // Connection established. Server sends 0x00000001 (invitation)
  2A 01 B9 06 00 0C 00 00  00 01 80 01 00 04 00 00  *...............
  FF FF                                             ..

  // Client sends auth cookie
  2A 01 01 07 01 08 00 00  00 01 00 06 01 00 7B F3  *.............{.
  F0 F3 A4 A5 6C 67 C5 DF  4B 78 4C 43 C7 6C 3D 44  ....lg..KxLC.l=D
  32 8D 96 82 DA 6A 41 7E  83 27 F4 D9 B8 A5 83 6B  2....jA~.'.....k
  54 95 1B 91 B9 FE 6D A3  B6 86 FC 21 C7 F0 53 C1  T.....m....!..S.
  A5 38 D6 07 D7 CA AA 7F  3E B6 FE D9 AD D7 AE 31  .8......>......1
  1B 6A A4 52 40 23 38 25  98 40 73 96 E7 17 B8 31  .j.R@#8%.@s....1
  C3 44 E8 98 15 1F DD E0  5C 31 48 7B 7D E5 92 E8  .D......\1H{}...
  35 14 C4 1E 1C 9C 4F FB  F8 55 76 B1 68 DB CE 72  5.....O..Uv.h..r
  06 43 1A 77 78 12 83 AD  EB 27 D3 2D 2A 69 47 A5  .C.wx....'.-*iG.
  FC DE C5 89 16 2E 74 52  BB 5C 6B BE 66 86 AB 83  ......tR.\k.f...
  3E C3 7C E8 24 C5 16 CE  4A 34 13 95 1B E4 56 35  >.|.$...J4....V5
  EA 18 FC D5 F7 24 0F 64  6A E6 D4 5D BF 14 57 CE  .....$.dj..]..W.
  4B 1D 7E CF 8F FD 1F CA  35 FA 29 97 21 DC F7 1C  K.~.....5.).!...
  1A 36 24 CD CC 5F 05 9C  44 A6 23 DF BB 09 B2 36  .6$.._..D.#....6
  17 36 91 26 0B 84 75 EA  D2 FC BD 70 0F C6 6C 67  .6.&..u....p..lg
  D0 64 99 82 A4 C2 00 10  D8 8C FF D9 71 9F 50 25  .d..........q.P%
  8A 2A BD C6 5E 27 8B 33  BE 81 21 D1 2B 4B        .*..^'.3..!.+K

  // Server sends supported services list - SNAC(01,03)
  2A 02 B9 07 00 0E 00 01  00 03 00 00 81 2E E2 C4  *...............
  00 01 00 10                                       ....

  // Client ask for services version numbers - SNAC(01,17)
  2A 02 01 08 00 12 00 01  00 17 00 00 00 00 00 17  *...............
  00 01 00 04 00 10 00 01                           ........

  // Server sends its services version numbers - SNAC(01,18)
  2A 02 B9 08 00 12 00 01  00 18 00 00 81 2E E2 E4  *...............
  00 01 00 04 00 10 00 01                           ........

  // Client ask server for rate limits info - SNAC(01,06)
  2A 02 01 09 00 0A 00 01  00 06 00 00 00 00 00 06  *...............

  //  Server sends rate limits information - SNAC(01,07)
  2A 02 B9 09 01 97 00 01  00 07 00 00 00 00 00 06  *...............
  00 05 00 01 00 00 00 50  00 00 09 C4 00 00 07 D0  .......P........
  00 00 05 DC 00 00 03 20  00 00 16 E4 00 00 17 70  ....... .......p
  00 00 00 00 00 00 02 00  00 00 50 00 00 0B B8 00  ..........P.....
  00 07 D0 00 00 05 DC 00  00 03 E8 00 00 17 70 00  ..............p.
  00 17 70 00 00 03 16 00  00 03 00 00 00 14 00 00  ..p.............
  13 EC 00 00 13 88 00 00  0F A0 00 00 0B B8 00 00  ................
  17 70 00 00 17 70 00 00  03 16 00 00 04 00 00 00  .p...p..........
  14 00 00 15 7C 00 00 14  B4 00 00 10 68 00 00 0B  ....|.......h...
  B8 00 00 17 70 00 00 1F  40 00 00 03 16 00 00 05  ....p...@.......
  00 00 00 0A 00 00 15 7C  00 00 14 B4 00 00 10 68  .......|.......h
  00 00 0B B8 00 00 17 70  00 00 1F 40 00 00 03 16  .......p...@....
  00 00 01 00 30 00 01 00  01 00 01 00 02 00 01 00  ....0...........
  03 00 01 00 04 00 01 00  05 00 01 00 06 00 01 00  ................
  07 00 01 00 08 00 01 00  09 00 01 00 0A 00 01 00  ................
  0B 00 01 00 0C 00 01 00  0D 00 01 00 0E 00 01 00  ................
  0F 00 01 00 10 00 01 00  11 00 01 00 12 00 01 00  ................
  13 00 01 00 14 00 01 00  15 00 01 00 16 00 01 00  ................
  17 00 01 00 18 00 01 00  19 00 01 00 1A 00 01 00  ................
  1B 00 01 00 1C 00 01 00  1D 00 01 00 1F 00 01 00  ................
  20 00 01 00 21 00 01 00  22 00 01 00 23 00 01 00   ...!..."...#...
  24 00 01 00 25 00 10 00  01 00 10 00 03 00 10 00  $...%...........
  04 00 10 00 05 00 10 00  06 00 10 00 07 00 10 00  ................
  08 00 10 00 09 00 10 00  0A 00 10 00 0B 00 10 00  ................
  0C 00 10 00 0D 00 02 00  00 00 03 00 02 00 01 00  ................
  1E 00 10 00 02 00 04 00  00 00 05 00 00           .............

  // Client ack connection rate limits - SNAC(01,08)
  2A 02 01 0A 00 14 00 01  00 08 00 00 00 00 00 08  *...............
  00 01 00 02 00 03 00 04  00 05                    ..........

  // Client sends READY command - SNAC(01,02)
  2A 02 01 0B 00 1A 00 01  00 02 00 00 00 00 00 02  *...............
  00 01 00 04 00 10 08 E4  00 10 00 01 00 10 08 E4  ................

  // Now client starts use this service - SNAC(10,06)
  2A 02 01 0C 00 29 00 10  00 06 00 00 2A 95 00 06  *....)......*...
  09 33 34 38 39 33 34 37  37 34 01 00 01 01 10 0B  .348934774......
  56 66 D6 16 5E 31 75 20  8D 3F 0C 38 38 87 4C     Vf..^1u .?.88.L

  ........

 
 


From Aleksandr Shutko: Service request sequence

 OSCAR sequences   



  Service request sequence description
 

     Service request is a way to get service not supported by BOS server. For example AOL server currently doesn't support SSBI service on main BOS connection. So service request is a first thing you should do if you want to deal with SSBI. This sequence looks like login, but not so complicated. Just look at the sequence example dump here.

 Correct service request sequence
  >>   SNAC(01,04)   Client ask server for service on BOS connection
  <<   SNAC(01,05)   Server reply with ip addres, port and auth cookie to client
  Now client makes connection to specified service server
  <>   connect   Client connects to service server
  >>   cli_cookie   Client sends cookie
  <<   SNAC(01,03)   Server sends supported services list
  >>   SNAC(01,17)   Client ask for services version numbers
  <<   SNAC(01,18)   Server sends its services version numbers
  >>   SNAC(01,06)   Client ask server for rate limits info
  <<   SNAC(01,07)   Server sends rate limits information
  >>   SNAC(01,08)   Client ack connection rate limits
  >>   SNAC(01,02)   Client READY command
  Now client have BOS & service connections...



OSERVICE SNACs

SNAC List
Subgroup Origin Name
0x0001 Any OSERVICE__ERR
This is the error SNAC for the OSERVICE foodgroup.
0x0002 Client OSERVICE__CLIENT_ONLINE
This message is sent by the client once it has initialized the host state (set preferences, Buddy Lists, locate information, capabilities) and is ready to be announced as being online by the host.
0x0003 Host OSERVICE__HOST_ONLINE
This is the very first SNAC sent from the host to the client after the FLAP signon frames are sent. It contains an array of all of the foodgroups the service supports.
0x0004 Client OSERVICE__SERVICE_REQUEST
This SNAC requests that the specified service (foodgroup) be provided to it in a way further specified by qualifying parameters.
0x0005 Host OSERVICE__SERVICE_RESPONSE
This SNAC contains information about connecting to the new server. It is the response from the server to a service request.
0x0006 Client OSERVICE__RATE_PARAMS_QUERY
This SNAC is sent by the client to query for the current rate limit parameters.
0x0007 Host OSERVICE__RATE_PARAMS_REPLY
Contains response to the OSERVICE__RATE_PARAMS_QUERY.
0x0008 Client OSERVICE__RATE_PARAMS_SUB_ADD
Subscribe to any rate parameter changes among the specified class IDs. If there was no prior subscription for a given class ID, an immediate notification will be queued.
0x0009 Client OSERVICE__RATE_DEL_PARAM_SUB
Cancels any rate parameter subscriptions for the specified class IDs.
0x000A Host OSERVICE__RATE_PARAM_CHANGE
This contains an array of class rate parameters that have changed since last query or notification.
0x000B Host OSERVICE__PAUSE_REQ
This is sent by the server when it needs to migrate the client.
0x000C Client OSERVICE__PAUSE_ACK
This is sent by the client to acknowledge the receipt and processing of a OSERVICE__PAUSE_REQ SNAC request.
0x000D Host OSERVICE__RESUME
In certain situations the server may abort a migration after having told the client to PAUSE.
0x000E Client OSERVICE__USER_INFO_QUERY
This is a query to find out one's current info. The server will send a OSERVICE__USER_INFO_UPDATE.
0x000F Host OSERVICE__USER_INFO_UPDATE
This SNAC is sent by the server whenever significant parts of a user's info change.
0x0010 Host OSERVICE__EVIL_NOTIFICATION
This is a notice that the user's evil level has changed.
0x0011 Client OSERVICE__IDLE_NOTIFICATION
This SNAC is sent by the client to inform the server of the user's idle state.
0x0012 Host OSERVICE__MIGRATE_GROUPS
This SNAC commands the client to reconnect to the server specified by the included OSERVICE__TLV_TAGS_RECONNECT_HERE TLV.
0x0013 Host OSERVICE__MOTD
Message of the day (MOTD). Often contains upgrade information for clients as well as notices about clients.
0x0014 Client OSERVICE__SET_PRIVACY_FLAGS
Set privacy flags.
0x0015 Host OSERVICE__WELL_KNOWN_URLS
Service related URLs for the client to use or provide to the user.
0x0016 Client OSERVICE__NOOP
Legacy SNAC keepalive, replaced in large part with FLAP level keepalive.
0x0017 Client OSERVICE__CLIENT_VERSIONS
Sent after OSERVICE__HOST_ONLINE, it contains the client's foodgroup version list so the host knows what functionality the client is capable of.
0x0018 Host OSERVICE__HOST_VERSIONS
The host responds to OSERVICE__CLIENT_VERSIONS with its foodgroup version list so that the client knows what this host provides and its capabilities.
0x0019 NCD OSERVICE__MAX_CONFIG_QUERY
This is not currently documented. Want to contribute?
0x001A NCD OSERVICE__MAX_CONFIG_REPLY
This is not currently documented. Want to contribute?
0x001B NCD OSERVICE__STORE_CONFIG
This is not currently documented. Want to contribute?
0x001C NCD OSERVICE__CONFIG_QUERY
This is not currently documented. Want to contribute?
0x001D NCD OSERVICE__CONFIG_REPLY
This is not currently documented. Want to contribute?
0x001E Client OSERVICE__SET_USERINFO_FIELDS
This allows the client to set some of the fields in user info that are sent to every client.
0x001F Host OSERVICE__PROBE_REQ
Client verification request.
0x0020 Client OSERVICE__PROBE_ACK
Client verification reply.
0x0021 Host OSERVICE__BART_REPLY
This reply is used to tell the client that a BART item needs to be uploaded or changed.
0x0022 Client OSERVICE__BART_QUERY2
This query sees if the BART IDs are available; OSERVICE__BART_REPLY2 is sent as a response.
0x0023 Host OSERVICE__BART_REPLY2
This SNAC is sent on initial login about items in the personality section of the Feedbag. It is also used in response to a OSERVICE__BART_QUERY2.