Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion Readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,17 @@ This library does not yet return limited attributes based on query strings, like
## ⚡️ Basic Use

1. Build vrc-oscquery-lib into vrc-oscquery-lib.dll and add it to your project (will make this a NuGet package once it's ready for wider use).
2. Construct a new OSCQuery service with `new OSCQueryServiceBuilder().WithDefaults().Build()`. T optionally passing in the name, TCP port to use for serving HTTP, UDP port that you're using for OSC, and an ILogger if you want logs.
2. Construct a new OSCQuery service.
- **Important**: If you want to customize settings (name, ports, etc.), configure them **before** calling `WithDefaults()`, as `WithDefaults()` immediately starts the HTTP server and advertising.
```csharp
var service = new OSCQueryServiceBuilder()
.WithTcpPort(Extensions.GetAvailableTcpPort())
.WithUdpPort(Extensions.GetAvailableUdpPort())
.WithServiceName("MyService")
.WithDefaults()
.Build();
```

3. You should now be able to visit `http://localhost:tcpPort` in a browser and see raw JSON describing an empty root node.
- You can also visit `http://localhost:tcpPort?explorer` to see an OSCQuery Explorer UI for the OSCQuery service, which should be easier to navigate than the raw JSON.
4. You can also visit `http://localhost:tcpPort?HOST_INFO` to get information about the supported attributes of this OSCQuery Server.
Expand Down
8 changes: 5 additions & 3 deletions getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ The format is always `new OSCQueryServiceBuilder()`, followed by all the things
There's a lot of options you _can_ configure if you want more control over what happens. The additional methods are listed below. Note that if you do not add any fluent options, then `WithDefaults()` is called for you automatically.

* WithDefaults()
* **Important**: This immediately starts the HTTP server and advertising. Configure all settings (ports, names, etc.) **before** calling this method.
* Sets up Discovery, Advertising and HTTP serving using default names and ports.
* WithTcpPort(int port)
* Set the TCP port you want to use for serving the HTTP endpoints. Defaults to any available open TCP port.
Expand All @@ -53,15 +54,16 @@ There's a lot of options you _can_ configure if you want more control over what
* AddListenerForServiceType(Action\<OSCQueryServiceProfile\> listener, OSCQueryServiceProfile.ServiceType type)
* Adds a listener which will be sent OSCQueryServiceProfiles for newly-discovered OSC or OSCQuery services.

You can can add these onto `.WithDefaults()` if you want _almost_ all the defaults. For example, this code will have all the defaults, but find the first available TCP port instead of 8060, and uses the name "MyService" instead of "OSCQueryService".
**Important**: You must configure settings **before** calling `.WithDefaults()`, as `WithDefaults()` immediately starts the HTTP server and advertising. Settings configured after `WithDefaults()` will not be applied.

```csharp
var oscQuery = new OSCQueryServiceBuilder()
.WithDefaults()
.WithTcpPort(Extensions.GetAvailableTcpPort())
.WithServiceName("MyService")
.WithDefaults()
.Build();
```

## A Simple Example

A minimal example for a working OSCQuery Service could look like this:
Expand All @@ -71,10 +73,10 @@ var tcpPort = Extensions.GetAvailableTcpPort();
var udpPort = Extensions.GetAvailableUdpPort();

var oscQuery = new OSCQueryServiceBuilder()
.WithDefaults()
.WithTcpPort(tcpPort)
.WithUdpPort(udpPort)
.WithServiceName("MyService")
.WithDefaults() // Configure settings BEFORE calling WithDefaults()
.Build();

// Manually logging the ports to see them without a logger
Expand Down