diff --git a/README.md b/README.md index f29b4b0..403acd9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # Discordgo -Golang DiscordApp API. +Golang Discord API. This is my first Golang project and it is probably not even suitable for use :) Everything here so far is likely to change as I learn Golang better and refine the API names and such. @@ -12,7 +12,7 @@ If you're looking for a functional Discord API for Golang check out https://gith -# Other DiscordApp APIs +# Other Discord APIs - [go-discord](https://github.com/gdraynz/go-discord) - [discord-go](https://github.com/Xackery/discord) - [discord.py](https://github.com/Rapptz/discord.py) diff --git a/discord.go b/discord.go index 8ef436d..c7b8a27 100644 --- a/discord.go +++ b/discord.go @@ -1,6 +1,6 @@ /****************************************************************************** * Discordgo v0 by Bruce Marriner - * A DiscordApp API for Golang. + * A Discord API for Golang. * * Currently only the REST API is functional. I will add on the websocket * layer once I get the API section where I want it. @@ -9,7 +9,8 @@ package discordgo -// Define known API URL paths as global constants +// These will absolutely change. I already don't like them. +// Constants that define the different Discord API URLs. const ( discordUrl = "http://discordapp.com" discordApi = discordUrl + "/api/" @@ -18,18 +19,17 @@ const ( users = discordApi + "users" ) -// possible all-inclusive strut.. +// A Discord structure represents a all-inclusive (hopefully) structure to +// access the Discord REST API for a given authenticated user. type Discord struct { - Session + Session Session User User Servers []Server } -// Create a new connection to Discord API. Returns a client session handle. -// this is a all inclusive type of easy setup command that will return -// a connection, user information, and available channels. -// This is probably the most common way to use the library but you -// can use the "manual" functions below instead. +// New creates a new connection to Discord and returns a Discord structure. +// This provides an easy entry where most commonly needed information is +// automatically fetched. func New(email string, password string) (discord *Discord, err error) { session := Session{} @@ -50,3 +50,15 @@ func New(email string, password string) (discord *Discord, err error) { return } + +// Renew essentially reruns the New command without creating a new session. +// This will update all the user, server, and channel information that was +// fetched with the New command. This is not an efficient way of doing this +// but if used infrequently it does provide convenience. +func (discord Discord) Renew() (err error) { + + discord.User, err = discord.Session.Self() + discord.Servers, err = discord.Session.Servers() + + return +} diff --git a/session.go b/session.go index 6ceeb9b..c198710 100644 --- a/session.go +++ b/session.go @@ -1,10 +1,6 @@ /****************************************************************************** - * Discordgo v0 by Bruce Marriner - * A DiscordApp API for Golang. - * - * Currently only the REST API is functional. I will add on the websocket - * layer once I get the API section where I want it. - * + * Discordgo by Bruce Marriner + * A Discord API for Golang. */ package discordgo @@ -19,14 +15,15 @@ import ( "time" ) -// Represents a session connection to the Discord REST API. -// I suspect I'll be adding more to this later :) +// A Session represents a connection to the Discord REST API. +// Token : The authentication token returned from Discord +// Debug : If set to ture debug logging will be displayed. type Session struct { Token string Debug bool } -// RequestToken asks the Rest server for a token by provided email/password +// RequestToken asks the Discord server for an authentication token func (session *Session) RequestToken(email string, password string) (token string, err error) { var urlStr string = fmt.Sprintf("%s/%s", discordApi, "auth/login") @@ -65,7 +62,7 @@ func (session *Session) RequestToken(email string, password string) (token strin return } -// Identify session user +// Self returns a User structure of the session authenticated user. func (session *Session) Self() (user User, err error) { body, err := Request(session, fmt.Sprintf("%s/%s", discordApi, "users/@me")) @@ -74,9 +71,7 @@ func (session *Session) Self() (user User, err error) { return } -// Request makes a API GET Request. This is a general purpose function -// and is used by all API functions. It is exposed currently so it can -// also be used outside of this library. +// Request makes a REST API GET Request with Discord. func Request(session *Session, urlStr string) (body []byte, err error) { req, err := http.NewRequest("GET", urlStr, bytes.NewBuffer([]byte(fmt.Sprintf(``)))) @@ -115,7 +110,8 @@ func Request(session *Session, urlStr string) (body []byte, err error) { return } -// Get all of the session user's private channels. +// PrivateChannels returns an array of Channel structures for all private +// channels of the session authenticated user. func (session *Session) PrivateChannels() (channels []Channel, err error) { body, err := Request(session, fmt.Sprintf("%s/%s", discordApi, fmt.Sprintf("users/@me/channels"))) @@ -124,7 +120,8 @@ func (session *Session) PrivateChannels() (channels []Channel, err error) { return } -// Get all of the session user's servers +// Servers returns an array of Server structures for all servers for the +// session authenticated user. func (session *Session) Servers() (servers []Server, err error) { body, err := Request(session, fmt.Sprintf("%s/%s", discordApi, fmt.Sprintf("users/@me/guilds"))) @@ -133,7 +130,8 @@ func (session *Session) Servers() (servers []Server, err error) { return } -// Get all channels for the given server +// Channels returns an array of Channel structures for all channels of a given +// server. func (session *Session) Channels(serverId int) (channels []Channel, err error) { body, err := Request(session, fmt.Sprintf("%s/%s", discordApi, fmt.Sprintf("guilds/%d/channels", serverId)))